@dudousxd/nestjs-durable-core 0.72.1 → 0.74.0

package/dist/index.cjs

@@ -56,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,
@@ -86,6 +88,7 @@ __export(index_exports, {
   capableWorkers: () => capableWorkers,
   classifyWaiterToken: () => classifyWaiterToken,
   clearDurableExecutionWrappers: () => clearDurableExecutionWrappers,
+  clearTerminalSingletonAdmission: () => clearTerminalSingletonAdmission,
   collectMetrics: () => collectMetrics,
   concurrencyTag: () => concurrencyTag,
   controlPlaneDescriptor: () => controlPlaneDescriptor,
@@ -114,6 +117,7 @@ __export(index_exports, {
   isLegacyDescriptor: () => isLegacyDescriptor,
   isNonEmptyRunScope: () => isNonEmptyRunScope,
   isWorkflowControlFlowSignal: () => isWorkflowControlFlowSignal,
+  listSignalWaitersOfRuns: () => listSignalWaitersOfRuns,
   log: () => log,
   matchesAttributes: () => matchesAttributes,
   mergeRunFacetRows: () => mergeRunFacetRows,
@@ -124,6 +128,7 @@ __export(index_exports, {
   normalizeAttributeRows: () => normalizeAttributeRows,
   normalizeDescriptor: () => normalizeDescriptor,
   observedAnnouncements: () => observedAnnouncements,
+  parentRunIdOf: () => parentRunIdOf,
   parseDuration: () => parseDuration,
   partitionOfToken: () => partitionOfToken,
   planDispatch: () => planDispatch,
@@ -143,6 +148,8 @@ __export(index_exports, {
   runValueFacetsFromRuns: () => runValueFacetsFromRuns,
   sanitizeQueueToken: () => sanitizeQueueToken,
   scheduledRunId: () => scheduledRunId,
+  singletonAdmissionDenialPatch: () => singletonAdmissionDenialPatch,
+  singletonAdmissionTags: () => singletonAdmissionTags,
   sqlComparator: () => sqlComparator,
   stepConfigOf: () => stepConfigOf,
   stepId: () => stepId,
@@ -545,12 +552,15 @@ var WorkflowSuspended = class extends Error {
   }
   /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
   wakeAt;
+  /** Set when awaited children are what the run is waiting on — see {@link FanJoin}. */
+  fan;
   /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
   [CONTROL_FLOW_SIGNAL] = true;
-  constructor(wakeAt) {
+  constructor(wakeAt, fan) {
     super("workflow suspended");
     this.name = "WorkflowSuspended";
     this.wakeAt = wakeAt;
+    this.fan = fan;
   }
 };
 var ContinueAsNew = class extends Error {
@@ -977,6 +987,21 @@ function instantCheckpoint(p) {
 }
 __name(instantCheckpoint, "instantCheckpoint");
 
+// src/completion.ts
+function isFailedCompletion(payload) {
+  const c = payload;
+  return !!c && typeof c === "object" && "ok" in c && c.ok === false;
+}
+__name(isFailedCompletion, "isFailedCompletion");
+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/concurrency.ts
 var DEFAULT_CONCURRENCY_STATUSES = [
   "pending",
@@ -1216,6 +1241,81 @@ function eventMatches(payload, match) {
 }
 __name(eventMatches, "eventMatches");
 
+// src/fan-join.ts
+function allChildId(runId, firstSeq, index, wave) {
+  return `${allBase(runId, firstSeq, wave)}${index}`;
+}
+__name(allChildId, "allChildId");
+function allGroup(firstSeq, mode) {
+  return mode === "failFast" ? `all:${firstSeq}:failFast` : `all:${firstSeq}`;
+}
+__name(allGroup, "allGroup");
+function allWait(runId, firstSeq, wave) {
+  const base = allBase(runId, firstSeq, wave);
+  return {
+    waiterPrefix: `child:${base}`,
+    checkpointPrefix: `signal:child:${base}`
+  };
+}
+__name(allWait, "allWait");
+function fanJoin(waits) {
+  return {
+    waits
+  };
+}
+__name(fanJoin, "fanJoin");
+var FOLDED_PREFIX = "fan:";
+function allFoldedName(runId, firstSeq, wave) {
+  return `${FOLDED_PREFIX}${allBase(runId, firstSeq, wave)}`;
+}
+__name(allFoldedName, "allFoldedName");
+function foldedChildIds(checkpoint) {
+  const base = checkpoint.name.slice(FOLDED_PREFIX.length);
+  const { from, values } = checkpoint.output;
+  return values.map((_, j) => `${base}${from + j}`);
+}
+__name(foldedChildIds, "foldedChildIds");
+function allBase(runId, firstSeq, wave) {
+  return wave === void 0 ? `${runId}.all.${firstSeq}.` : `${runId}.all.${firstSeq}.w${wave}.`;
+}
+__name(allBase, "allBase");
+function allWaves(size, concurrency) {
+  if (concurrency === void 0 || concurrency >= size) return void 0;
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error(`ctx.all: concurrency must be a positive integer, got ${concurrency}`);
+  }
+  if (concurrency === 1) return {
+    waveSize: 1,
+    maxWaves: 1
+  };
+  return {
+    waveSize: Math.floor(concurrency / 2),
+    maxWaves: 2
+  };
+}
+__name(allWaves, "allWaves");
+var ENGINE_CHILD_ID = /^(.+)\.(?:all\.\d+\.(?:w\d+\.)?\d+|child\.\d+)$/;
+function parentRunIdOf(runId) {
+  return ENGINE_CHILD_ID.exec(runId)?.[1];
+}
+__name(parentRunIdOf, "parentRunIdOf");
+var GROUP = /^all:(\d+)(:failFast)?$/;
+var REST = /^(?:w(\d+)\.)?\d+$/;
+function fanOfWaiter(waiter) {
+  const group = waiter.parallelGroup ? GROUP.exec(waiter.parallelGroup) : null;
+  if (!group) return void 0;
+  const base = `child:${waiter.runId}.all.${group[1]}.`;
+  if (!waiter.token.startsWith(base)) return void 0;
+  const rest = REST.exec(waiter.token.slice(base.length));
+  if (!rest) return void 0;
+  const waiterPrefix = rest[1] === void 0 ? base : `${base}w${rest[1]}.`;
+  return {
+    waiterPrefix,
+    failFast: group[2] !== void 0
+  };
+}
+__name(fanOfWaiter, "fanOfWaiter");
+
 // src/handshake/descriptor.ts
 var CURRENT_PROTOCOL_VERSION = 1;
 var LEGACY_V1_PROTOCOL = {
@@ -1957,6 +2057,23 @@ function resolveRunWaiting(run, waiterByRun) {
   return waiter ? classifyWaiterToken(waiter.token) : void 0;
 }
 __name(resolveRunWaiting, "resolveRunWaiting");
+var RUN_ID_BATCH = 500;
+async function listSignalWaitersOfRuns(store, runIds) {
+  const unique = [
+    ...new Set(runIds)
+  ];
+  if (unique.length === 0) return [];
+  if (!store.listSignalWaitersByRun) {
+    const ids = new Set(unique);
+    return (await store.listSignalWaiters("")).filter((w) => ids.has(w.runId));
+  }
+  const out = [];
+  for (let at = 0; at < unique.length; at += RUN_ID_BATCH) {
+    out.push(...await store.listSignalWaitersByRun(unique.slice(at, at + RUN_ID_BATCH)));
+  }
+  return out;
+}
+__name(listSignalWaitersOfRuns, "listSignalWaitersOfRuns");
 function indexWaitersByRun(waiters) {
   const byRun = /* @__PURE__ */ new Map();
   for (const w of waiters) if (!byRun.has(w.runId)) byRun.set(w.runId, w);
@@ -2444,6 +2561,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;
@@ -2457,6 +2622,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. */
@@ -2465,7 +2633,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) {
@@ -2474,34 +2642,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
@@ -2725,16 +2884,6 @@ var TransportPool = class {
   }
 };
 
-// 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/step-name-symbol.ts
 var DURABLE_STEP_NAME = Symbol.for("durable.step.name");
 var DURABLE_STEP_CONFIG = Symbol.for("durable.step.config");
@@ -2756,6 +2905,8 @@ function stepConfigOf(ref) {
 __name(stepConfigOf, "stepConfigOf");
 
 // src/workflow-ctx.ts
+var FAN_CHUNK = 500;
+var FOLD_MIN_FAN = 100;
 function normalizeChildOptions(options) {
   return typeof options === "string" ? {
     childId: options
@@ -3098,7 +3249,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     if (existing && existing.status === "completed") {
       return unwrapCompletion(existing.output, `child "${id}"`);
     }
-    await store.putSignalWaiter({
+    if (!existing) await store.putSignalWaiter({
       token: `child:${id}`,
       runId,
       seq: current
@@ -3129,16 +3280,33 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         status: "running"
       }));
     }
-    throw new WorkflowSuspended();
+    throw new WorkflowSuspended(void 0, fanJoin([
+      {
+        waiterPrefix: `child:${id}`,
+        checkpointPrefix: `signal:child:${id}`
+      }
+    ]));
   }, "child");
   const all = /* @__PURE__ */ __name(async (workflow2, inputs, opts) => {
     if (inputs.length === 0) return [];
     const mode = opts?.mode ?? "waitAll";
     const name = workflowName(workflow2);
+    const waves = allWaves(inputs.length, opts?.concurrency);
     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)));
+    const firstSeq = positions[0];
+    const group = allGroup(firstSeq, mode);
+    const waveOf = /* @__PURE__ */ __name((i) => waves ? Math.floor(i / waves.waveSize) : void 0, "waveOf");
+    const id = /* @__PURE__ */ __name((i) => allChildId(runId, firstSeq, i, waveOf(i)), "id");
+    const { checkpoints: existing, folded } = await readFan(positions, [
+      allWait(runId, firstSeq).checkpointPrefix,
+      allFoldedName(runId, firstSeq)
+    ]);
+    const waveCount = waves ? Math.ceil(inputs.length / waves.waveSize) : 1;
+    const waveItems = /* @__PURE__ */ __name((k) => {
+      if (!waves) return inputs.map((_, i) => i);
+      const from = k * waves.waveSize;
+      return inputs.map((_, i) => i).slice(from, from + waves.waveSize);
+    }, "waveItems");
     if (mode === "failFast") {
       for (let i = 0; i < inputs.length; i += 1) {
         const cp = existing[i];
@@ -3157,32 +3325,91 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         }
       }
     }
-    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({
+    if (store.compactCheckpoints && inputs.length >= FOLD_MIN_FAN) {
+      for (let k = 0; k < waveCount; k += 1) {
+        const items = waveItems(k);
+        const first = items[0];
+        const last = items[items.length - 1];
+        if (folded[first]) continue;
+        const values = [];
+        for (const i of items) {
+          const c = existing[i]?.status === "completed" ? existing[i]?.output : void 0;
+          if (!c || typeof c !== "object" || c.ok !== true) break;
+          values.push(c.value);
+        }
+        if (values.length < items.length) continue;
+        const into = instantCheckpoint({
           runId,
-          seq,
-          name: `signal:child:${childId}`,
+          seq: positions[first],
+          name: allFoldedName(runId, firstSeq, waves ? k : void 0),
           kind: "signal",
-          status: "running",
+          output: {
+            from: first,
+            values
+          },
           parallelGroup: group
+        });
+        await store.compactCheckpoints(runId, positions[first], positions[last], into);
+        for (const i of items) replay?.delete(positions[i]);
+        replay?.set(into.seq, into);
+      }
+    }
+    const sent = /* @__PURE__ */ __name((k) => waveItems(k).some((i) => existing[i]), "sent");
+    const settled = /* @__PURE__ */ __name((k) => waveItems(k).every((i) => existing[i]?.status === "completed"), "settled");
+    const active = [];
+    let unsettled = 0;
+    for (let k = 0; k < waveCount; k += 1) {
+      if (settled(k)) continue;
+      if (sent(k) || unsettled < (waves?.maxWaves ?? 1)) {
+        active.push(k);
+        unsettled += 1;
+      }
+    }
+    if (active.length > 0) {
+      const toRegister = [];
+      const toEnsure = [];
+      for (const k of active) {
+        for (const i of waveItems(k)) {
+          const cp = existing[i];
+          if (cp?.status === "completed") continue;
+          (cp ? toEnsure : toRegister).push(i);
+        }
+      }
+      for (let at = 0; at < toRegister.length; at += FAN_CHUNK) {
+        const chunk = toRegister.slice(at, at + FAN_CHUNK);
+        const entries = chunk.map((i) => ({
+          // Carry the fan `group` onto the waiter too: the child's terminal `signal:child:`
+          // checkpoint is (re)written by engine.signal when the child notifies the parent,
+          // OVERWRITING the running placeholder at the same seq — so without this the resolved
+          // checkpoint would lose the group and the dashboard would render the resolved fan as a
+          // sequential chain.
+          waiter: {
+            token: `child:${id(i)}`,
+            runId,
+            seq: positions[i],
+            parallelGroup: group
+          },
+          checkpoint: instantCheckpoint({
+            runId,
+            seq: positions[i],
+            name: `signal:child:${id(i)}`,
+            kind: "signal",
+            status: "running",
+            parallelGroup: group
+          })
+        }));
+        await registerChildWaits(entries);
+        for (const i of chunk) host.startChild(name, inputs[i], id(i));
+      }
+      for (let at = 0; at < toEnsure.length; at += FAN_CHUNK) {
+        await Promise.all(toEnsure.slice(at, at + FAN_CHUNK).map(async (i) => {
+          if (!await store.getRun(id(i))) host.startChild(name, inputs[i], id(i));
         }));
       }
     }
-    if (pending) throw new WorkflowSuspended();
+    if (active.length > 0) {
+      throw new WorkflowSuspended(void 0, fanJoin(active.map((k) => allWait(runId, firstSeq, waves ? k : void 0))));
+    }
     const outputs = [];
     const failures = [];
     for (let i = 0; i < inputs.length; i += 1) {
@@ -3201,6 +3428,67 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     if (failures.length > 0) throw new GatherError(failures, inputs.length);
     return outputs;
   }, "all");
+  const readFan = /* @__PURE__ */ __name(async (positions, prefixes) => {
+    const checkpoints = positions.map((seq) => replay?.get(seq) ?? null);
+    const folded = positions.map(() => false);
+    const expand = /* @__PURE__ */ __name(() => {
+      for (let i = 0; i < checkpoints.length; i += 1) {
+        const cp = checkpoints[i];
+        if (!cp?.name.startsWith(FOLDED_PREFIX) || folded[i]) continue;
+        const fold = cp.output;
+        if (!fold || typeof fold.from !== "number" || !Array.isArray(fold.values)) {
+          throw new Error(`ctx.all: folded checkpoint "${cp.name}" at seq ${cp.seq} is malformed`);
+        }
+        const { from, values } = fold;
+        values.forEach((value, j) => {
+          checkpoints[from + j] = {
+            ...cp,
+            seq: positions[from + j],
+            output: {
+              ok: true,
+              value
+            }
+          };
+          folded[from + j] = true;
+        });
+      }
+    }, "expand");
+    expand();
+    const missing = positions.filter((_, i) => !checkpoints[i]);
+    if (missing.length === 0) return {
+      checkpoints,
+      folded
+    };
+    if (missing.length > 1 && store.listCheckpointsByNamePrefix) {
+      const bySeq = /* @__PURE__ */ new Map();
+      for (const cp of await store.listCheckpointsByNamePrefix(runId, prefixes)) {
+        bySeq.set(cp.seq, cp);
+      }
+      positions.forEach((seq, i) => {
+        checkpoints[i] ??= bySeq.get(seq) ?? null;
+      });
+    } else {
+      await Promise.all(positions.map(async (seq, i) => {
+        checkpoints[i] ??= await readCheckpoint(seq);
+      }));
+    }
+    expand();
+    return {
+      checkpoints,
+      folded
+    };
+  }, "readFan");
+  const registerChildWaits = /* @__PURE__ */ __name(async (entries) => {
+    if (store.registerChildWaits) {
+      await store.registerChildWaits(entries);
+    } else {
+      await Promise.all(entries.map(async (e) => {
+        await store.putSignalWaiter(e.waiter);
+        await store.saveCheckpoint(e.checkpoint);
+      }));
+    }
+    for (const e of entries) replay?.set(e.checkpoint.seq, e.checkpoint);
+  }, "registerChildWaits");
   const startChild = /* @__PURE__ */ __name(async (workflow2, input, options) => {
     const { childId, priority, version } = normalizeChildOptions(options);
     const current = pos.next();
@@ -4018,7 +4306,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);
     }
@@ -4093,6 +4381,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)`);
@@ -4234,15 +4528,16 @@ var WorkflowEngine = class {
   */
   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;
+    const waiters = await this.store.listSignalWaiters(token);
+    return waiters.find((waiter) => waiter.token === token)?.runId;
   }
   /** 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;
   }
   /**
@@ -4455,7 +4750,10 @@ var WorkflowEngine = class {
     const due = await this.store.listDueTimers(nowMs, this.namespace);
     const blocked = await this.dueBlockedRuns(nowMs);
     if (due.length === 0 && blocked.length === 0) return [];
-    const waiterByRun = indexWaitersByRun(await this.store.listSignalWaiters(""));
+    const waiterByRun = indexWaitersByRun(await listSignalWaitersOfRuns(this.store, [
+      ...due,
+      ...blocked
+    ].map((run) => run.id)));
     return this.resumeLeased([
       ...due,
       ...blocked
@@ -4565,11 +4863,6 @@ var WorkflowEngine = class {
             } : {}
           });
         } else if (cp.kind === "signal" && cp.name.startsWith("signal:child:") && cp.status === "completed" && isFailureCompletion(cp.output)) {
-          await this.store.saveCheckpoint({
-            ...cp,
-            status: "running",
-            output: void 0
-          });
           const childId = cp.name.slice("signal:child:".length);
           const parked = [];
           for (; ; ) {
@@ -4577,8 +4870,28 @@ var WorkflowEngine = class {
             if (!buffered) break;
             parked.push(buffered.payload);
           }
+          const successAt = parked.findIndex((payload) => typeof payload === "object" && payload !== null && payload.ok === true);
+          const success = successAt === -1 ? void 0 : parked.splice(successAt, 1)[0];
           for (const payload of parked) await this.store.bufferSignal(`child:${childId}`, payload);
-          const bufferedSuccess = parked.some((payload) => typeof payload === "object" && payload !== null && payload.ok === true);
+          const bufferedSuccess = success !== void 0;
+          if (bufferedSuccess) {
+            await this.store.saveCheckpoint({
+              ...cp,
+              output: success
+            });
+          } else {
+            await this.store.putSignalWaiter({
+              token: `child:${childId}`,
+              runId,
+              seq: cp.seq,
+              parallelGroup: cp.parallelGroup
+            });
+            await this.store.saveCheckpoint({
+              ...cp,
+              status: "running",
+              output: void 0
+            });
+          }
           if (!bufferedSuccess) {
             const child = await this.store.getRun(childId);
             if (child && (child.status === "failed" || child.status === "dead")) {
@@ -4593,7 +4906,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()
     });
@@ -4712,10 +5026,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);
@@ -4848,12 +5171,62 @@ var WorkflowEngine = class {
       // for an ordinary (non-fan) signal/child await.
       parallelGroup: waiter.parallelGroup
     }));
+    if (await this.fanStillWaiting(waiter, payload)) {
+      return {
+        runId: waiter.runId,
+        status: "suspended"
+      };
+    }
     return this.resumeImplicit(waiter.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
   }
   /**
+  * The `ctx.all` join barrier: true when `waiter` was one child of a fan (or of one wave of it)
+  * whose siblings are still out, so waking the parent now would only replay the fan and re-suspend.
+  * Skipping that wake is what keeps a fan of N children at O(N) work instead of N replays of N items.
+  *
+  * Safe because the LAST sibling to settle always wakes the parent: each child consumes its own
+  * waiter before it asks, so whichever asks last sees none left. A failed child of a failFast fan
+  * always wakes it. Anything that is not a `ctx.all` waiter, or a store that cannot answer the
+  * question cheaply, wakes the parent as before.
+  */
+  async fanStillWaiting(waiter, payload) {
+    if (!this.store.hasSignalWaiter) return false;
+    const fan = fanOfWaiter(waiter);
+    if (!fan) return false;
+    if (fan.failFast && isFailedCompletion(payload)) return false;
+    return this.store.hasSignalWaiter(waiter.runId, fan.waiterPrefix);
+  }
+  /**
+  * Re-drive a run that just suspended on awaited children (a `ctx.all` fan or wave, a `ctx.child`)
+  * which, by now, have settled.
+  *
+  * {@link execute} drops a wake that finds the run's lease held. So if a child settles while the
+  * parent is still executing (the turn that dispatched it, or one woken by an earlier child), that
+  * wake is spent, and the turn suspends on a snapshot that predates the child. With the `ctx.all`
+  * barrier that wake was the only one the fan would get. Nothing would wake the run until the
+  * `reconcileMs` sweep, minutes later.
+  *
+  * Called after the turn released its lease, so any child that settles from here on wakes the run
+  * itself. Only re-drives for a group with no waiter left whose checkpoints are all settled, which
+  * the next turn is then guaranteed to see — so it cannot loop.
+  */
+  async redriveSettledChildren(runId, fan) {
+    if (!this.store.hasSignalWaiter) return;
+    for (const wait of fan.waits) {
+      if (await this.store.hasSignalWaiter(runId, wait.waiterPrefix)) continue;
+      const checkpoints = this.store.listCheckpointsByNamePrefix ? await this.store.listCheckpointsByNamePrefix(runId, [
+        wait.checkpointPrefix
+      ]) : (await this.store.listCheckpoints(runId)).filter((cp) => cp.name.startsWith(wait.checkpointPrefix));
+      if (checkpoints.length > 0 && checkpoints.every((cp) => cp.status === "completed")) {
+        await this.resumeImplicit(runId);
+        return;
+      }
+    }
+  }
+  /**
   * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
   * the run result — or null if no run is (or ends up) waiting for it.
   *
@@ -5146,23 +5519,11 @@ var WorkflowEngine = class {
   }
   /** The given runs plus every descendant, children before parents. One waiter scan for the batch. */
   async collectSubtrees(rootIds) {
-    const waitersByParent = /* @__PURE__ */ new Map();
-    for (const w of await this.store.listSignalWaiters("child:")) {
-      const list = waitersByParent.get(w.runId) ?? [];
-      list.push(w.token.slice("child:".length));
-      waitersByParent.set(w.runId, list);
-    }
-    const prefixes = [
-      "signal:child:",
-      "spawn:"
-    ];
+    const prefixes = CHILD_EDGE_PREFIXES;
     const childrenOf = /* @__PURE__ */ __name(async (parent) => {
-      const ids = new Set(waitersByParent.get(parent) ?? []);
+      const ids = new Set(await this.awaitedChildIds(parent));
       const cps = this.store.listCheckpointsByNamePrefix ? await this.store.listCheckpointsByNamePrefix(parent, prefixes) : (await this.store.listCheckpoints(parent)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
-      for (const cp of cps) {
-        if (cp.name.startsWith("signal:child:")) ids.add(cp.name.slice("signal:child:".length));
-        if (cp.name.startsWith("spawn:") && typeof cp.output === "string") ids.add(cp.output);
-      }
+      for (const id of childIdsOf(cps)) ids.add(id);
       return [
         ...ids
       ];
@@ -5212,22 +5573,20 @@ var WorkflowEngine = class {
   * 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.
+  * dedupe — the edge stays stable for a finished run, not just a live one. A settled `ctx.all`
+  * group folded into one `fan:` checkpoint stands for every child in it.
   */
+  /** The children `parentRunId` is awaiting right now, read off its own live `child:` waiters. */
+  async awaitedChildIds(parentRunId) {
+    return (await listSignalWaitersOfRuns(this.store, [
+      parentRunId
+    ])).filter((w) => w.token.startsWith("child:")).map((w) => w.token.slice("child:".length));
+  }
   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 childIds = new Set(await this.awaitedChildIds(parentRunId));
+    const prefixes = CHILD_EDGE_PREFIXES;
     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);
-    }
+    for (const id of childIdsOf(childCheckpoints)) childIds.add(id);
     return [
       ...childIds
     ];
@@ -5498,6 +5857,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();
@@ -5667,23 +6046,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);
@@ -6297,28 +6660,13 @@ 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);
     const replay = /* @__PURE__ */ new Map();
     for (const cp of snapshot) replay.set(cp.seq, cp);
+    let suspendedOnFan;
     const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow, registered?.searchAttributesSchema);
     try {
       const output = await runInWorkflowCtx(ctx, () => fn(ctx, run.input));
@@ -6370,10 +6718,12 @@ var WorkflowEngine = class {
         if (this.cancelRequested.has(run.id)) {
           return await this.compensateAndCancel(run, compensations, replay);
         }
-        return await this.settleRun(run, {
+        const suspended = await this.settleRun(run, {
           kind: "suspended",
           wakeAt: err.wakeAt
         });
+        suspendedOnFan = err.fan;
+        return suspended;
       }
       if (this.cancelRequested.has(run.id)) {
         return await this.compensateAndCancel(run, compensations, replay);
@@ -6393,6 +6743,9 @@ var WorkflowEngine = class {
       });
     } finally {
       await this.store.releaseRunLock(run.id);
+      if (suspendedOnFan) {
+        void this.redriveSettledChildren(run.id, suspendedOnFan).catch(() => void 0);
+      }
     }
   }
   /**
@@ -7207,6 +7560,21 @@ var RemoteStepError = class extends Error {
     this.stepError = stepError;
   }
 };
+var CHILD_EDGE_PREFIXES = [
+  "signal:child:",
+  FOLDED_PREFIX,
+  "spawn:"
+];
+function childIdsOf(checkpoints) {
+  const ids = [];
+  for (const cp of checkpoints) {
+    if (cp.name.startsWith("signal:child:")) ids.push(cp.name.slice("signal:child:".length));
+    if (cp.name.startsWith(FOLDED_PREFIX)) ids.push(...foldedChildIds(cp));
+    if (cp.name.startsWith("spawn:") && typeof cp.output === "string") ids.push(cp.output);
+  }
+  return ids;
+}
+__name(childIdsOf, "childIdsOf");
 
 // src/run-facets.ts
 function facetOrigin(origin) {
@@ -7332,6 +7700,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
@@ -7354,6 +7724,14 @@ var CodecStateStore = class {
   /** Forwarded verbatim — a count reads no payload. Bound only when the inner store counts, so the
   *  engine's facet/listing fallback still applies through the wrapper. */
   countRuns;
+  /** The placeholder checkpoints are encoded like any other checkpoint. */
+  registerChildWaits;
+  /** The folded checkpoint carries the children's outputs, so it is encoded. */
+  compactCheckpoints;
+  /** Forwarded verbatim — a waiter carries no payload. */
+  listSignalWaitersByRun;
+  /** Forwarded verbatim — a waiter carries no payload. */
+  hasSignalWaiter;
   /** Schedules persist their run `input` inside `spec` — encoded like any other payload. Bound only
   *  when the inner store persists schedules, so `engine.schedules` reports absence faithfully. */
   saveSchedule;
@@ -7364,12 +7742,24 @@ 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;
     if (prune) this.pruneTerminalRuns = (policy, now, limit) => prune.call(inner, policy, now, limit);
     const count = inner.countRuns;
     if (count) this.countRuns = (query) => count.call(inner, query);
+    const registerChildWaits = inner.registerChildWaits;
+    if (registerChildWaits) this.registerChildWaits = (entries) => registerChildWaits.call(inner, entries.map((e) => ({
+      waiter: e.waiter,
+      checkpoint: this.encCp(e.checkpoint)
+    })));
+    const compact = inner.compactCheckpoints;
+    if (compact) this.compactCheckpoints = (runId, fromSeq, toSeq, into) => compact.call(inner, runId, fromSeq, toSeq, this.encCp(into));
+    const byRun = inner.listSignalWaitersByRun;
+    if (byRun) this.listSignalWaitersByRun = (runIds) => byRun.call(inner, runIds);
+    const hasWaiter = inner.hasSignalWaiter;
+    if (hasWaiter) this.hasSignalWaiter = (runId, tokenPrefix) => hasWaiter.call(inner, runId, tokenPrefix);
     const { saveSchedule, getSchedule, updateSchedule, deleteSchedule, listSchedules } = inner;
     if (saveSchedule && getSchedule && updateSchedule && deleteSchedule && listSchedules) {
       this.saveSchedule = (r) => saveSchedule.call(inner, this.encSchedule(r));
@@ -7816,6 +8206,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,
@@ -7823,7 +8235,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 = {
@@ -7954,6 +8370,33 @@ var InMemoryStateStore = class {
       ...w
     }));
   }
+  async registerChildWaits(entries) {
+    for (const { waiter } of entries) this.signalWaiters.set(waiter.token, {
+      ...waiter
+    });
+    for (const { checkpoint } of entries) await this.saveCheckpoint(checkpoint);
+  }
+  async compactCheckpoints(runId, fromSeq, toSeq, into) {
+    for (let seq = fromSeq; seq <= toSeq; seq += 1) this.checkpoints.delete(this.key(runId, seq));
+    this.checkpoints.set(this.key(runId, into.seq), {
+      ...into,
+      runId
+    });
+  }
+  async listSignalWaitersByRun(runIds) {
+    const ids = new Set(runIds);
+    return [
+      ...this.signalWaiters.values()
+    ].filter((w) => ids.has(w.runId)).map((w) => ({
+      ...w
+    }));
+  }
+  async hasSignalWaiter(runId, tokenPrefix) {
+    for (const w of this.signalWaiters.values()) {
+      if (w.runId === runId && w.token.startsWith(tokenPrefix)) return true;
+    }
+    return false;
+  }
   async removeSignalWaiter(waiter) {
     const current = this.signalWaiters.get(waiter.token);
     if (current && current.runId === waiter.runId && current.seq === waiter.seq) {
@@ -8248,6 +8691,8 @@ var InMemoryTransport = class {
   RemoteWorkflowExecutor,
   RemoteWorkflowTimeout,
   RunGateway,
+  SINGLETON_ACTIVE_STATUSES,
+  SINGLETON_ADMITTED_TAG,
   STATE_STORE,
   STATE_STORE_CANONICAL,
   ScheduleAlreadyExistsError,
@@ -8278,6 +8723,7 @@ var InMemoryTransport = class {
   capableWorkers,
   classifyWaiterToken,
   clearDurableExecutionWrappers,
+  clearTerminalSingletonAdmission,
   collectMetrics,
   concurrencyTag,
   controlPlaneDescriptor,
@@ -8306,6 +8752,7 @@ var InMemoryTransport = class {
   isLegacyDescriptor,
   isNonEmptyRunScope,
   isWorkflowControlFlowSignal,
+  listSignalWaitersOfRuns,
   log,
   matchesAttributes,
   mergeRunFacetRows,
@@ -8316,6 +8763,7 @@ var InMemoryTransport = class {
   normalizeAttributeRows,
   normalizeDescriptor,
   observedAnnouncements,
+  parentRunIdOf,
   parseDuration,
   partitionOfToken,
   planDispatch,
@@ -8335,6 +8783,8 @@ var InMemoryTransport = class {
   runValueFacetsFromRuns,
   sanitizeQueueToken,
   scheduledRunId,
+  singletonAdmissionDenialPatch,
+  singletonAdmissionTags,
   sqlComparator,
   stepConfigOf,
   stepId,