@dudousxd/nestjs-durable-core 0.38.0 → 0.39.0

package/dist/index.d.cts

@@ -1503,6 +1503,16 @@ declare class WorkflowEngine {
      * 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: string, version: string, fn: WorkflowFn, opts?: {
         tags?: string[] | undefined;
@@ -1511,7 +1521,22 @@ declare class WorkflowEngine {
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
         onEvent?: string[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
+        /** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
+         *  Omit for the default inline fast path. See the method doc. */
+        group?: string | undefined;
+        /** Advances a turn by dispatching a {@link WorkflowTask} to `group`. Requires `group`. For an
+         *  in-app worker, pair a transport-backed {@link RemoteWorkflowExecutor} (group consumed by a
+         *  worker that calls {@link workflowBody}) so the retained `fn` runs through the transport hop. */
+        executor?: WorkflowExecutor | undefined;
     }): void;
+    /**
+     * 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: string, version: string): WorkflowFn | undefined;
     /**
      * 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
@@ -1575,6 +1600,49 @@ declare class WorkflowEngine {
     /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
     getRun(runId: string): Promise<WorkflowRun | null>;
     resume(runId: string): Promise<RunResult>;
+    /**
+     * 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.
+     */
+    private findInheritedRegistration;
+    /**
+     * 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.
+     */
+    private synthesizeRemoteChild;
+    /**
+     * 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.
+     */
+    private findRemoteAncestor;
+    /**
+     * 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.
+     */
+    private findParentRunId;
     /** Track an in-flight execution so {@link drain} can wait for it. */
     private track;
     /**

package/dist/index.d.ts

@@ -1503,6 +1503,16 @@ declare class WorkflowEngine {
      * 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: string, version: string, fn: WorkflowFn, opts?: {
         tags?: string[] | undefined;
@@ -1511,7 +1521,22 @@ declare class WorkflowEngine {
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
         onEvent?: string[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
+        /** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
+         *  Omit for the default inline fast path. See the method doc. */
+        group?: string | undefined;
+        /** Advances a turn by dispatching a {@link WorkflowTask} to `group`. Requires `group`. For an
+         *  in-app worker, pair a transport-backed {@link RemoteWorkflowExecutor} (group consumed by a
+         *  worker that calls {@link workflowBody}) so the retained `fn` runs through the transport hop. */
+        executor?: WorkflowExecutor | undefined;
     }): void;
+    /**
+     * 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: string, version: string): WorkflowFn | undefined;
     /**
      * 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
@@ -1575,6 +1600,49 @@ declare class WorkflowEngine {
     /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
     getRun(runId: string): Promise<WorkflowRun | null>;
     resume(runId: string): Promise<RunResult>;
+    /**
+     * 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.
+     */
+    private findInheritedRegistration;
+    /**
+     * 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.
+     */
+    private synthesizeRemoteChild;
+    /**
+     * 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.
+     */
+    private findRemoteAncestor;
+    /**
+     * 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.
+     */
+    private findParentRunId;
     /** Track an in-flight execution so {@link drain} can wait for it. */
     private track;
     /**

package/dist/index.js

@@ -1626,8 +1626,21 @@ var WorkflowEngine = class {
   * 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,
@@ -1637,8 +1650,17 @@ var WorkflowEngine = class {
       executionTimeoutMs: opts?.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts?.validateInput,
       onEvent: opts?.onEvent,
-      eventBatch: opts?.eventBatch
+      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);
@@ -1649,6 +1671,17 @@ var WorkflowEngine = class {
     }
   }
   /**
+  * 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
@@ -1774,7 +1807,11 @@ var WorkflowEngine = class {
   }
   async start(workflow, input, runId, opts) {
     const name = workflowName(workflow);
-    const registered = this.latest.get(name);
+    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) throw new Error(`workflow ${name} is not registered`);
     await registered.validateInput?.(input);
     const prior = await this.store.getRun(runId);
@@ -1835,12 +1872,87 @@ var WorkflowEngine = class {
         error: run.error
       };
     }
-    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion));
+    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(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
+    };
+  }
+  /**
+  * 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);
@@ -2530,7 +2642,7 @@ var WorkflowEngine = class {
     });
   }
   async execute(run, fn) {
-    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion));
+    const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(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)) {