@dudousxd/nestjs-durable-core 0.72.0 → 0.73.0

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   InMemoryTransport: () => InMemoryTransport,
   LEGACY_V1_CAPABILITIES: () => LEGACY_V1_CAPABILITIES,
   LEGACY_V1_PROTOCOL: () => LEGACY_V1_PROTOCOL,
+  NestedWorkflowCallError: () => NestedWorkflowCallError,
   NonDeterminismError: () => NonDeterminismError,
   QueueController: () => QueueController,
   RUN_VALUE_FACET_LIMIT: () => RUN_VALUE_FACET_LIMIT,
@@ -55,6 +56,8 @@ __export(index_exports, {
   RemoteWorkflowExecutor: () => RemoteWorkflowExecutor,
   RemoteWorkflowTimeout: () => RemoteWorkflowTimeout,
   RunGateway: () => RunGateway,
+  SINGLETON_ACTIVE_STATUSES: () => SINGLETON_ACTIVE_STATUSES,
+  SINGLETON_ADMITTED_TAG: () => SINGLETON_ADMITTED_TAG,
   STATE_STORE: () => STATE_STORE,
   STATE_STORE_CANONICAL: () => STATE_STORE_CANONICAL,
   ScheduleAlreadyExistsError: () => ScheduleAlreadyExistsError,
@@ -85,6 +88,7 @@ __export(index_exports, {
   capableWorkers: () => capableWorkers,
   classifyWaiterToken: () => classifyWaiterToken,
   clearDurableExecutionWrappers: () => clearDurableExecutionWrappers,
+  clearTerminalSingletonAdmission: () => clearTerminalSingletonAdmission,
   collectMetrics: () => collectMetrics,
   concurrencyTag: () => concurrencyTag,
   controlPlaneDescriptor: () => controlPlaneDescriptor,
@@ -92,6 +96,7 @@ __export(index_exports, {
   coveredTokens: () => coveredTokens,
   createStepLogger: () => createStepLogger,
   currentStep: () => currentStep,
+  currentStepScope: () => currentStepScope,
   currentWorkflowCtx: () => currentWorkflowCtx,
   debug: () => debug,
   describeWorker: () => describeWorker,
@@ -133,12 +138,16 @@ __export(index_exports, {
   resolveRunWaiting: () => resolveRunWaiting,
   runDurableExecution: () => runDurableExecution,
   runInStepLogger: () => runInStepLogger,
+  runInStepScope: () => runInStepScope,
   runInWorkflowCtx: () => runInWorkflowCtx,
+  runOutsideWorkflowCtx: () => runOutsideWorkflowCtx,
   runSchedules: () => runSchedules,
   runStepHandler: () => runStepHandler,
   runValueFacetsFromRuns: () => runValueFacetsFromRuns,
   sanitizeQueueToken: () => sanitizeQueueToken,
   scheduledRunId: () => scheduledRunId,
+  singletonAdmissionDenialPatch: () => singletonAdmissionDenialPatch,
+  singletonAdmissionTags: () => singletonAdmissionTags,
   sqlComparator: () => sqlComparator,
   stepConfigOf: () => stepConfigOf,
   stepId: () => stepId,
@@ -324,6 +333,27 @@ function currentWorkflowCtx() {
   return storage.getStore();
 }
 __name(currentWorkflowCtx, "currentWorkflowCtx");
+var STEP_SCOPE_KEY = Symbol.for("nestjs-durable:ambient-step-scope");
+var stepScopeRef = globalThis;
+if (!stepScopeRef[STEP_SCOPE_KEY]) {
+  stepScopeRef[STEP_SCOPE_KEY] = new import_node_async_hooks.AsyncLocalStorage();
+}
+var stepScopeStorage = stepScopeRef[STEP_SCOPE_KEY];
+function runInStepScope(owner, step, fn) {
+  return stepScopeStorage.run({
+    owner,
+    step
+  }, fn);
+}
+__name(runInStepScope, "runInStepScope");
+function currentStepScope() {
+  return stepScopeStorage.getStore();
+}
+__name(currentStepScope, "currentStepScope");
+function runOutsideWorkflowCtx(fn) {
+  return storage.exit(() => stepScopeStorage.exit(fn));
+}
+__name(runOutsideWorkflowCtx, "runOutsideWorkflowCtx");
 
 // src/ambient-step.ts
 var import_node_async_hooks2 = require("async_hooks");
@@ -486,6 +516,21 @@ var NonDeterminismError = class extends Error {
     this.seq = seq;
   }
 };
+var NestedWorkflowCallError = class extends FatalError {
+  static {
+    __name(this, "NestedWorkflowCallError");
+  }
+  runId;
+  primitive;
+  step;
+  constructor(runId, primitive, step) {
+    super(`ctx.${primitive}() was called inside the body of step "${step}" (run ${runId}). Workflow primitives (child/startChild/step/sleep/signals/sideEffect/\u2026, and MyWorkflow.start()/.execute() via the ambient ctx) must be called from the workflow body, never from inside a step body: the step's checkpoint replays without re-running it, so the nested call would shift every later journal position and corrupt the run on replay. Move the call out of the step.`, "nested_workflow_call");
+    this.name = "NestedWorkflowCallError";
+    this.runId = runId;
+    this.primitive = primitive;
+    this.step = step;
+  }
+};
 var GatherError = class extends Error {
   static {
     __name(this, "GatherError");
@@ -842,14 +887,19 @@ async function runStepHandler(task, handler) {
   } : result, "withEvents");
   try {
     const logger = createStepLogger(events, Date.now);
-    const output = await runDurableExecution({
-      unit: "step",
-      runId: task.runId,
-      workflow: void 0,
-      name: task.name,
-      seq: task.seq,
-      attempt: task.attempt
-    }, async () => runInStepLogger(logger, () => handler(task.input, logger)));
+    const output = await runDurableExecution(
+      {
+        unit: "step",
+        runId: task.runId,
+        workflow: void 0,
+        name: task.name,
+        seq: task.seq,
+        attempt: task.attempt
+      },
+      // Outside any ambient workflow ctx: an in-process transport runs the handler on the parent
+      // body's async path, but a handler is not the body (see `runOutsideWorkflowCtx`).
+      async () => runOutsideWorkflowCtx(() => runInStepLogger(logger, () => handler(task.input, logger)))
+    );
     return withEvents({
       ...base,
       status: "completed",
@@ -2399,6 +2449,54 @@ function errorMessage(error2) {
 }
 __name(errorMessage, "errorMessage");
 
+// src/singleton-admission.ts
+var SINGLETON_ADMITTED_TAG = "durable:singleton:admitted";
+var SINGLETON_ACTIVE_STATUSES = [
+  "pending",
+  "running",
+  "suspended",
+  "blocked",
+  "cancelling"
+];
+function singletonAdmissionTags(runs, runId, tag, workflow, limit) {
+  if (!Number.isInteger(limit) || limit < 1) throw new Error("singleton limit must be a positive integer");
+  const active = runs.filter((run) => run.workflow === workflow && SINGLETON_ACTIVE_STATUSES.includes(run.status) && run.tags?.includes(tag));
+  const candidate = active.find((run) => run.id === runId);
+  if (!candidate) return null;
+  if (candidate.tags?.includes(SINGLETON_ADMITTED_TAG)) return candidate.tags;
+  if (candidate.status === "cancelling") return null;
+  const holders = active.filter((run) => run.tags?.includes(SINGLETON_ADMITTED_TAG));
+  const remaining = limit - holders.length;
+  if (remaining <= 0) return null;
+  const waiters = active.filter((run) => !run.tags?.includes(SINGLETON_ADMITTED_TAG)).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
+  if (!waiters.slice(0, remaining).some((run) => run.id === runId)) return null;
+  return [
+    ...candidate.tags ?? [],
+    SINGLETON_ADMITTED_TAG
+  ];
+}
+__name(singletonAdmissionTags, "singletonAdmissionTags");
+async function clearTerminalSingletonAdmission(runId, patch, getRun) {
+  if (!patch.status || !TERMINAL_RUN_STATUSES.includes(patch.status)) return patch;
+  const tags = "tags" in patch ? patch.tags : (await getRun(runId))?.tags;
+  return {
+    ...patch,
+    tags: tags?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG)
+  };
+}
+__name(clearTerminalSingletonAdmission, "clearTerminalSingletonAdmission");
+function singletonAdmissionDenialPatch(runs, runId, tag, workflow, retryWakeAt) {
+  if (retryWakeAt === void 0) return void 0;
+  const candidate = runs.find((run) => run.id === runId && run.workflow === workflow && run.tags?.includes(tag) && SINGLETON_ACTIVE_STATUSES.includes(run.status));
+  if (!candidate || candidate.status === "cancelling") return void 0;
+  return {
+    status: "suspended",
+    wakeAt: retryWakeAt,
+    updatedAt: /* @__PURE__ */ new Date()
+  };
+}
+__name(singletonAdmissionDenialPatch, "singletonAdmissionDenialPatch");
+
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -2412,6 +2510,9 @@ var SingletonGate = class {
   }
   /** The tag a singleton run carries, so the gate can find others sharing its key. */
   tag(cfg, input) {
+    if (!this.deps.store.tryAdmitSingleton) {
+      throw new Error("Singleton workflows require StateStore.tryAdmitSingleton for atomic durable admission");
+    }
     return `singleton:${cfg.key(input)}`;
   }
   /** Next wake time for a gated run: the base retry delay jittered to avoid a wakeup stampede. */
@@ -2420,7 +2521,7 @@ var SingletonGate = class {
   }
   /**
   * 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`
+  * `pending`/`running`/`suspended`/`blocked`/`cancelling` runs sharing the key in one scan). No-op when no `maxQueueDepth`
   * is configured.
   */
   async assertCapacity(workflow, cfg, input) {
@@ -2429,34 +2530,25 @@ var SingletonGate = class {
     const queued = await this.deps.store.listRuns({
       tag: this.tag(cfg, input),
       workflow,
-      statuses: [
-        "pending",
-        "running",
-        "suspended",
-        "cancelling"
-      ]
+      statuses: SINGLETON_ACTIVE_STATUSES
     });
     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.
-  */
+  /** Preserve durable holders and atomically claim one of the remaining slots. */
   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);
+    if (!this.deps.store.tryAdmitSingleton) {
+      throw new Error("Singleton workflows require StateStore.tryAdmitSingleton for atomic durable admission");
+    }
+    const admitted = await this.deps.store.tryAdmitSingleton(run.id, this.tag(cfg, run.input), run.workflow, cfg.limit ?? 1, this.retryWakeAt());
+    if (admitted && !run.tags?.includes(SINGLETON_ADMITTED_TAG)) {
+      run.tags = [
+        ...run.tags ?? [],
+        SINGLETON_ADMITTED_TAG
+      ];
+    }
+    return admitted;
   }
   /**
   * Notify-on-release: a singleton run settled (freeing a slot), so dispatch the oldest gated
@@ -2753,10 +2845,15 @@ var Position = class Position2 {
   rewind() {
     this.seq -= 1;
   }
+  /** The position the NEXT primitive would claim, without claiming it. */
+  peek() {
+    return this.seq + 1;
+  }
 };
 function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttributesSchema) {
   const { store, replay } = host;
   const pos = new Position();
+  const scopeOwner = {};
   const readCheckpoint = /* @__PURE__ */ __name((seq) => {
     const hit = replay?.get(seq);
     if (hit !== void 0) return hit;
@@ -2802,7 +2899,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         };
         const body = /* @__PURE__ */ __name(() => {
           const logger = createStepLogger(events, host.clock);
-          return runInStepLogger(logger, () => fn(logger));
+          return runInStepScope(scopeOwner, name, () => runInStepLogger(logger, () => fn(logger)));
         }, "body");
         const output = host.interceptStep ? await host.interceptStep(invocation, body) : await body();
         await host.completeStep({
@@ -2855,7 +2952,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     }
     if (existing && existing.status === "completed") return existing.output;
     return store.transaction(async (tx) => {
-      const output = await fn(tx.raw);
+      const output = await runInStepScope(scopeOwner, name, () => fn(tx.raw));
       const cp = instantCheckpoint({
         runId,
         seq: current,
@@ -3364,30 +3461,49 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     });
   }
   __name(step, "step");
+  const nestedStep = /* @__PURE__ */ __name(() => {
+    const scope = currentStepScope();
+    return scope !== void 0 && scope.owner === scopeOwner ? scope.step : void 0;
+  }, "nestedStep");
+  const guard = /* @__PURE__ */ __name((primitive, fn) => (...args) => {
+    const stepName = nestedStep();
+    if (stepName === void 0) return fn(...args);
+    return (async () => {
+      if (await readCheckpoint(pos.peek())) return fn(...args);
+      throw new NestedWorkflowCallError(runId, primitive, stepName);
+    })();
+  }, "guard");
+  const guardedWebhook = /* @__PURE__ */ __name(() => {
+    const stepName = nestedStep();
+    if (stepName !== void 0 && !replay?.get(pos.peek())) {
+      throw new NestedWorkflowCallError(runId, "webhook", stepName);
+    }
+    return webhook();
+  }, "guardedWebhook");
   return {
     runId,
-    step,
-    localStep,
-    upsertSearchAttributes,
-    transaction,
-    callEntity,
-    signalEntity,
-    sleep,
-    sleepUntil,
+    step: guard("step", step),
+    localStep: guard("localStep", localStep),
+    upsertSearchAttributes: guard("upsertSearchAttributes", upsertSearchAttributes),
+    transaction: guard("transaction", transaction),
+    callEntity: guard("callEntity", callEntity),
+    signalEntity: guard("signalEntity", signalEntity),
+    sleep: guard("sleep", sleep),
+    sleepUntil: guard("sleepUntil", sleepUntil),
     continueAsNew,
-    waitForSignal,
-    waitForEvent,
-    task,
-    child,
-    all,
-    startChild,
-    breakpoint,
-    webhook,
-    setEvent,
-    onUpdate,
-    patched,
-    now,
-    sideEffect
+    waitForSignal: guard("waitForSignal", waitForSignal),
+    waitForEvent: guard("waitForEvent", waitForEvent),
+    task: guard("task", task),
+    child: guard("child", child),
+    all: guard("all", all),
+    startChild: guard("startChild", startChild),
+    breakpoint: guard("breakpoint", breakpoint),
+    webhook: guardedWebhook,
+    setEvent: guard("setEvent", setEvent),
+    onUpdate: guard("onUpdate", onUpdate),
+    patched: guard("patched", patched),
+    now: guard("now", now),
+    sideEffect: guard("sideEffect", sideEffect)
   };
 }
 __name(createWorkflowCtx, "createWorkflowCtx");
@@ -3949,7 +4065,7 @@ var WorkflowEngine = class {
         VERSION_UNDECLARED_TAG
       ] : []
     ];
-    const tags = mergeTags(registered.tags, stampedTags);
+    const tags = mergeTags(registered.tags, stampedTags)?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG);
     if (registered.singleton) {
       await this.singletons.assertCapacity(name, registered.singleton, input);
     }
@@ -3989,10 +4105,30 @@ var WorkflowEngine = class {
   getRun(runId) {
     return this.store.getRun(runId);
   }
-  async resume(runId) {
+  /**
+  * Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
+  * driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
+  * also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
+  * dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
+  * timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
+  * terminal too.
+  */
+  resume(runId) {
+    return this.resumeRun(runId, true);
+  }
+  /**
+  * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
+  * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
+  * these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
+  * stale waiter or a late result left behind by a failed run silently re-executes its body.
+  */
+  resumeImplicit(runId) {
+    return this.resumeRun(runId, false);
+  }
+  async resumeRun(runId, allowFailed) {
     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") {
+    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead" || run.status === "failed" && !allowFailed) {
       return {
         runId,
         status: run.status,
@@ -4004,6 +4140,12 @@ var WorkflowEngine = class {
       await this.store.releaseRunLock(runId);
       throw new NamespaceMismatch();
     }
+    if (run.status === "failed" && run.tags?.includes(SINGLETON_ADMITTED_TAG)) {
+      run.tags = run.tags.filter((tag) => tag !== SINGLETON_ADMITTED_TAG);
+      await this.store.updateRun(run.id, {
+        tags: run.tags
+      });
+    }
     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)`);
@@ -4153,7 +4295,10 @@ var WorkflowEngine = class {
   /** 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));
+    const done = /* @__PURE__ */ __name(() => {
+      this.inflight.delete(p);
+    }, "done");
+    void p.then(done, done);
     return p;
   }
   /**
@@ -4441,7 +4586,7 @@ var WorkflowEngine = class {
     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) => {
+    return this.resumeImplicit(runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -4504,7 +4649,8 @@ var WorkflowEngine = class {
       status: "pending",
       error: void 0,
       ...resurrecting ? {
-        recoveryAttempts: 0
+        recoveryAttempts: 0,
+        tags: run.tags?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG)
       } : {},
       updatedAt: /* @__PURE__ */ new Date()
     });
@@ -4623,10 +4769,19 @@ var WorkflowEngine = class {
         off();
         resolve(toResult(run));
       }, "finish");
+      const fail = /* @__PURE__ */ __name((error2) => {
+        if (done) return;
+        done = true;
+        if (timer) clearTimeout(timer);
+        if (poller) clearInterval(poller);
+        off();
+        reject(error2);
+      }, "fail");
       const check = /* @__PURE__ */ __name(() => {
+        if (done) return;
         void this.store.getRun(runId).then((run) => {
           if (run && isSettled(run)) finish(run);
-        });
+        }, fail);
       }, "check");
       const poller = opts?.until === "terminal" ? (() => {
         const interval = setInterval(check, 250);
@@ -4662,7 +4817,7 @@ var WorkflowEngine = class {
       if (!acquired) continue;
       try {
         const settled = onLocked ? await onLocked(run) : void 0;
-        results.push(settled ?? await this.resume(run.id));
+        results.push(settled ?? await this.resumeImplicit(run.id));
       } catch (error2) {
         console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, error2);
       }
@@ -4759,7 +4914,7 @@ var WorkflowEngine = class {
       // for an ordinary (non-fan) signal/child await.
       parallelGroup: waiter.parallelGroup
     }));
-    return this.resume(waiter.runId).catch((err) => {
+    return this.resumeImplicit(waiter.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -4875,7 +5030,7 @@ var WorkflowEngine = class {
   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") {
+    if (TERMINAL_RUN_STATUSES.includes(run.status)) {
       return {
         runId,
         status: run.status,
@@ -4904,7 +5059,7 @@ var WorkflowEngine = class {
         }).catch(() => void 0);
       }
       queueMicrotask(() => {
-        void this.resume(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
+        void this.resumeImplicit(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
       });
       await this.cancelChildren(runId, opts);
       return {
@@ -5409,6 +5564,26 @@ var WorkflowEngine = class {
       durationMs: Date.now() - step.startedAt.getTime()
     });
   }
+  /** Admission persists the wait atomically; never overwrite a cancellation after it returns. */
+  async singletonWaitResult(run) {
+    const current = await this.store.getRun(run.id);
+    await this.store.releaseRunLock(run.id);
+    if (!current) throw new Error(`run ${run.id} was deleted during singleton admission`);
+    if (current.status === "suspended") {
+      this.emit({
+        type: "run.suspended",
+        runId: current.id,
+        workflow: current.workflow,
+        namespace: current.namespace
+      });
+    }
+    return {
+      runId: current.id,
+      status: current.status,
+      output: current.output,
+      error: current.error
+    };
+  }
   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();
@@ -5578,23 +5753,7 @@ var WorkflowEngine = class {
       });
     }
     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,
-        namespace: run.namespace
-      });
-      await this.store.releaseRunLock(run.id);
-      return {
-        runId: run.id,
-        status: "suspended"
-      };
+      return this.singletonWaitResult(run);
     }
     const wfPlan = await this.planRoute(tenantGroup(sanitizeQueueToken(remote.group), void 0), registered.requires);
     if (wfPlan?.status === "blocked") return this.parkBlocked(run, wfPlan);
@@ -5739,7 +5898,7 @@ var WorkflowEngine = class {
       const checkpoint = await this.store.getCheckpoint(runId, cmd.seq);
       if (checkpoint && checkpoint.status !== "pending") {
         setTimeout(() => {
-          void this.resume(runId).catch(() => void 0);
+          void this.resumeImplicit(runId).catch(() => void 0);
         }, 0).unref?.();
         return;
       }
@@ -6081,7 +6240,7 @@ var WorkflowEngine = class {
             kind: "signal",
             output: payload
           }));
-          setTimeout(() => void this.resume(run.id).catch(() => void 0), 0);
+          setTimeout(() => void this.resumeImplicit(run.id).catch(() => void 0), 0);
         }, "deliverBuffered");
         const buffered = await this.store.takeBufferedSignal(cmd.signal);
         if (buffered) {
@@ -6208,23 +6367,7 @@ var WorkflowEngine = class {
       });
     }
     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,
-        namespace: run.namespace
-      });
-      await this.store.releaseRunLock(run.id);
-      return {
-        runId: run.id,
-        status: "suspended"
-      };
+      return this.singletonWaitResult(run);
     }
     const compensations = [];
     const snapshot = await this.store.listCheckpoints(run.id);
@@ -6895,7 +7038,7 @@ var WorkflowEngine = class {
       queueMs: startedAt.getTime() - cp.enqueuedAt.getTime(),
       durationMs: finishedAt.getTime() - startedAt.getTime()
     });
-    await this.resume(result.runId).catch((err) => {
+    await this.resumeImplicit(result.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -6996,7 +7139,7 @@ var WorkflowEngine = class {
       ...waiters
     ];
     waiters.clear();
-    for (const runId of runIds) void this.resume(runId).catch(() => void 0);
+    for (const runId of runIds) void this.resumeImplicit(runId).catch(() => void 0);
   }
   /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
   async releaseQueueSlot(id) {
@@ -7243,6 +7386,8 @@ var CodecStateStore = class {
   }
   inner;
   codec;
+  /** Atomic claims touch only searchable metadata and bypass payload encoding. */
+  tryAdmitSingleton;
   /**
   * Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
   * (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
@@ -7275,6 +7420,7 @@ var CodecStateStore = class {
   constructor(inner, codec) {
     this.inner = inner;
     this.codec = codec;
+    if (inner.tryAdmitSingleton) this.tryAdmitSingleton = inner.tryAdmitSingleton.bind(inner);
     const deleteRuns = inner.deleteRuns;
     if (deleteRuns) this.deleteRuns = (ids) => deleteRuns.call(inner, ids);
     const prune = inner.pruneTerminalRuns;
@@ -7727,6 +7873,28 @@ var InMemoryStateStore = class {
       byRun.set(runId, row);
     }
   }
+  async tryAdmitSingleton(runId, tag, workflow, limit, retryWakeAt) {
+    const runs = [
+      ...this.runs.values()
+    ];
+    const tags = singletonAdmissionTags(runs, runId, tag, workflow, limit);
+    if (!tags) {
+      const patch = singletonAdmissionDenialPatch(runs, runId, tag, workflow, retryWakeAt);
+      const candidate = this.runs.get(runId);
+      if (patch && candidate) this.runs.set(runId, {
+        ...candidate,
+        ...patch
+      });
+      return false;
+    }
+    const run = this.runs.get(runId);
+    if (!run) return false;
+    this.runs.set(runId, {
+      ...run,
+      tags
+    });
+    return true;
+  }
   async createRun(run) {
     this.runs.set(run.id, {
       ...run,
@@ -7734,7 +7902,11 @@ var InMemoryStateStore = class {
     });
     this.reindexAttributes(run.id, run.searchAttributes);
   }
-  async updateRun(runId, patch) {
+  async updateRun(runId, inputPatch) {
+    const patch = inputPatch.status && TERMINAL_RUN_STATUSES.includes(inputPatch.status) ? {
+      ...inputPatch,
+      tags: ("tags" in inputPatch ? inputPatch.tags : this.runs.get(runId)?.tags)?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG)
+    } : inputPatch;
     const existing = this.runs.get(runId);
     if (!existing) throw new Error(`run ${runId} not found`);
     const next = {
@@ -8149,6 +8321,7 @@ var InMemoryTransport = class {
   InMemoryTransport,
   LEGACY_V1_CAPABILITIES,
   LEGACY_V1_PROTOCOL,
+  NestedWorkflowCallError,
   NonDeterminismError,
   QueueController,
   RUN_VALUE_FACET_LIMIT,
@@ -8158,6 +8331,8 @@ var InMemoryTransport = class {
   RemoteWorkflowExecutor,
   RemoteWorkflowTimeout,
   RunGateway,
+  SINGLETON_ACTIVE_STATUSES,
+  SINGLETON_ADMITTED_TAG,
   STATE_STORE,
   STATE_STORE_CANONICAL,
   ScheduleAlreadyExistsError,
@@ -8188,6 +8363,7 @@ var InMemoryTransport = class {
   capableWorkers,
   classifyWaiterToken,
   clearDurableExecutionWrappers,
+  clearTerminalSingletonAdmission,
   collectMetrics,
   concurrencyTag,
   controlPlaneDescriptor,
@@ -8195,6 +8371,7 @@ var InMemoryTransport = class {
   coveredTokens,
   createStepLogger,
   currentStep,
+  currentStepScope,
   currentWorkflowCtx,
   debug,
   describeWorker,
@@ -8236,12 +8413,16 @@ var InMemoryTransport = class {
   resolveRunWaiting,
   runDurableExecution,
   runInStepLogger,
+  runInStepScope,
   runInWorkflowCtx,
+  runOutsideWorkflowCtx,
   runSchedules,
   runStepHandler,
   runValueFacetsFromRuns,
   sanitizeQueueToken,
   scheduledRunId,
+  singletonAdmissionDenialPatch,
+  singletonAdmissionTags,
   sqlComparator,
   stepConfigOf,
   stepId,