@dudousxd/nestjs-durable-core 0.38.0 → 0.40.0

package/dist/index.d.cts

@@ -246,6 +246,13 @@ interface WorkflowRun {
     tags?: string[] | undefined;
     /** Typed, queryable run data (e.g. `{ amount: 200, tier: 'pro' }`) — see {@link RunQuery.attributes}. */
     searchAttributes?: SearchAttributes | undefined;
+    /**
+     * The worker-pool partition this run belongs to. Stamped at creation from the creating engine's
+     * `namespace` (default `'default'`). A worker only picks up / recovers / resumes-timers-for /
+     * times-out runs in its own namespace. `undefined` on a run created before this field existed; the
+     * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
+     */
+    namespace?: string | undefined;
     /**
      * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
      * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
@@ -433,11 +440,11 @@ interface StateStore {
      */
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     /**
      * Atomically acquire the recovery lease on a run for `owner` until `leaseUntilMs`, but only if
      * it is currently unlocked or its lease has expired (`<= nowMs`). Returns whether it was
@@ -549,6 +556,8 @@ interface RunQuery {
      * `workflow`/`status`/`tag` to bound the scan on large stores.
      */
     attributes?: AttributeFilter[] | undefined;
+    /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
+    namespace?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -1336,6 +1345,13 @@ interface WorkflowEngineDeps {
     admission?: AdmissionBackend | undefined;
     /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
     instanceId?: string | undefined;
+    /**
+     * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
+     * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
+     * namespace. Default `'default'` — byte-identical to a single-pool deployment. Set distinct values
+     * to safely share ONE state store across non-interchangeable pools (e.g. local dev vs a cluster).
+     */
+    namespace?: string | undefined;
     /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
     leaseMs?: number | undefined;
     /**
@@ -1427,6 +1443,7 @@ declare class WorkflowEngine {
     private readonly controlPlane?;
     private readonly clock;
     private readonly instanceId;
+    private readonly namespace;
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
@@ -1503,6 +1520,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 +1538,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 +1617,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;
     /**
@@ -2078,9 +2163,9 @@ declare class CodecStateStore implements StateStore {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
     }) => Promise<T>): Promise<T>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
@@ -2342,9 +2427,9 @@ declare class InMemoryStateStore implements StateStore {
     deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;

package/dist/index.d.ts

@@ -246,6 +246,13 @@ interface WorkflowRun {
     tags?: string[] | undefined;
     /** Typed, queryable run data (e.g. `{ amount: 200, tier: 'pro' }`) — see {@link RunQuery.attributes}. */
     searchAttributes?: SearchAttributes | undefined;
+    /**
+     * The worker-pool partition this run belongs to. Stamped at creation from the creating engine's
+     * `namespace` (default `'default'`). A worker only picks up / recovers / resumes-timers-for /
+     * times-out runs in its own namespace. `undefined` on a run created before this field existed; the
+     * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
+     */
+    namespace?: string | undefined;
     /**
      * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
      * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
@@ -433,11 +440,11 @@ interface StateStore {
      */
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
     /** The oldest `pending` runs awaiting dispatch (FIFO, by `createdAt`), capped at `limit`. */
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** Suspended runs whose durable timer is due (`wakeAt <= nowMs`), ready to resume. */
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     /**
      * Atomically acquire the recovery lease on a run for `owner` until `leaseUntilMs`, but only if
      * it is currently unlocked or its lease has expired (`<= nowMs`). Returns whether it was
@@ -549,6 +556,8 @@ interface RunQuery {
      * `workflow`/`status`/`tag` to bound the scan on large stores.
      */
     attributes?: AttributeFilter[] | undefined;
+    /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
+    namespace?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -1336,6 +1345,13 @@ interface WorkflowEngineDeps {
     admission?: AdmissionBackend | undefined;
     /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
     instanceId?: string | undefined;
+    /**
+     * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
+     * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
+     * namespace. Default `'default'` — byte-identical to a single-pool deployment. Set distinct values
+     * to safely share ONE state store across non-interchangeable pools (e.g. local dev vs a cluster).
+     */
+    namespace?: string | undefined;
     /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
     leaseMs?: number | undefined;
     /**
@@ -1427,6 +1443,7 @@ declare class WorkflowEngine {
     private readonly controlPlane?;
     private readonly clock;
     private readonly instanceId;
+    private readonly namespace;
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
@@ -1503,6 +1520,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 +1538,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 +1617,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;
     /**
@@ -2078,9 +2163,9 @@ declare class CodecStateStore implements StateStore {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
     }) => Promise<T>): Promise<T>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;
@@ -2342,9 +2427,9 @@ declare class InMemoryStateStore implements StateStore {
     deleteRun(runId: string): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
-    listIncompleteRuns(): Promise<WorkflowRun[]>;
-    listPendingRuns(limit: number): Promise<WorkflowRun[]>;
-    listDueTimers(nowMs: number): Promise<WorkflowRun[]>;
+    listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
+    listDueTimers(nowMs: number, namespace?: string): Promise<WorkflowRun[]>;
     tryLockRun(runId: string, owner: string, leaseUntilMs: number, nowMs: number): Promise<boolean>;
     releaseRunLock(runId: string): Promise<void>;
     renewRunLock(runId: string, owner: string, leaseUntilMs: number): Promise<boolean>;