@dudousxd/nestjs-durable 0.30.2 → 0.31.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { StepError, WorkflowRef, SingletonConfig, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, GroupHealth, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, EngineEvent, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, StepCheckpoint, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowRun } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -51,6 +52,8 @@ interface WorkflowMeta {
     inputSchema?: (new (...args: any[]) => object) | undefined;
     /** Custom input validator (throws on invalid). See `WorkflowOptions`. */
     validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+    /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
+    searchAttributes?: SearchAttributesSchema | undefined;
     /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
     onEvent?: string[] | undefined;
     /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
@@ -102,6 +105,32 @@ interface WorkflowOptions {
      * `inputSchema`. Takes precedence over `inputSchema` if both are set.
      */
     validateInput?: (input: unknown) => void | Promise<void>;
+    /**
+     * Validate this workflow's {@link WorkflowCtx.upsertSearchAttributes} writes against a **Standard
+     * Schema** (https://standardschema.dev — zod 3.24+, valibot, arktype, …). `ctx.upsertSearchAttributes`
+     * validates the MERGED result (existing attributes shallow-merged with the patch) on every call —
+     * an invalid merge throws, naming this workflow, the offending key(s), and the schema's issues. The
+     * schema's inferred output must be search-attribute-shaped (flat `string`/`number`/`boolean` values
+     * only) — a schema whose output has a nested object/array is a compile-time error here. Omit for
+     * the prior unvalidated behavior.
+     *
+     * ```ts
+     * import { z } from 'zod';
+     *
+     * const orderAttrs = z.object({
+     *   tier: z.enum(['free', 'pro']),
+     *   amount: z.number(),
+     * });
+     *
+     * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+     * class CheckoutWorkflow {
+     *   async run(ctx: WorkflowCtx<InferSearchAttributes<typeof orderAttrs>>, input: CheckoutInput) {
+     *     await ctx.upsertSearchAttributes({ tier: input.tier, amount: input.total });
+     *   }
+     * }
+     * ```
+     */
+    searchAttributes?: SearchAttributesSchema;
     /**
      * Start a fresh run of this workflow whenever any of these events is published via
      * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
@@ -289,6 +318,10 @@ interface DurableRetentionOptions {
  *
  * `forRoot` throws when neither `store` nor `connection` is set, and when `store` is set without a
  * `transport`.
+ *
+ * Set {@link DurableModuleOptions.topology} to name the role explicitly instead of relying on this
+ * inference — it additionally VALIDATES the axes above (`namespace` vs `partition`) that this prose
+ * is otherwise the only source of truth for. Omitting it changes nothing.
  */
 interface DurableModuleOptions {
     /** State store — set this to play the **operator** role (see the interface doc for the full role
@@ -478,6 +511,47 @@ interface DurableModuleOptions {
     /** Timeout for a thin worker's `RunGateway` round-trip over `transport` before it rejects. Defaults
      *  to 10_000ms inside `ProxyRunGateway`. Ignored for an operator (bound to `StoreRunGateway`). */
     runGatewayTimeoutMs?: number;
+    /**
+     * An explicit preset that NAMES the deployment role instead of leaving it to `store`/`connection`
+     * inference, and VALIDATES the axes that are otherwise only prose (see the interface doc's role
+     * matrix, and {@link namespace} vs {@link partition}). Omit to keep the existing inference —
+     * `topology` is entirely additive and changes nothing when unset.
+     *
+     * **`namespace` vs `partition` — the two axes this preset locks down:**
+     * - `namespace` is the OPERATOR's poll-scoping axis: which runs a control-plane instance
+     *   drives/recovers/resumes (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`).
+     *   Unset makes the instance see (drive) EVERY namespace.
+     *   `{ role: 'control-plane' }` is the only preset that allows it.
+     * - `partition` is the WORKER's queue-routing suffix: which queue a thin/co-located worker's
+     *   consumer subscribes to (`<name>@<partition>`), matching the queue an operator's convention
+     *   dispatch routes a run's `namespace` to. `{ role: 'tenant' }` sets this FOR you from `tenant` —
+     *   you never set `partition` directly under `topology`.
+     *
+     * ```ts
+     * // Control plane: owns the store, dispatches over the transport, prunes old runs.
+     * DurableModule.forRoot({
+     *   topology: { role: 'control-plane' },
+     *   store,
+     *   transport,
+     *   retention: { policies: [{ statuses: ['completed', 'cancelled'], maxAge: '14d' }] },
+     * });
+     *
+     * // Tenant: store-less worker scoped to its own partition — `tenant` maps to `partition` for you.
+     * DurableModule.forRoot({
+     *   topology: { role: 'tenant', tenant: 'acme-corp' },
+     *   connection: process.env.REDIS_URL,
+     * });
+     * ```
+     *
+     * Validated at `forRoot`/`forRootAsync` resolution time — see {@link DurableModule} for the exact
+     * error messages, which double as the axis primer above.
+     */
+    topology?: {
+        role: 'control-plane';
+    } | {
+        role: 'tenant';
+        tenant: string;
+    };
 }
 interface DurableModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
@@ -486,6 +560,14 @@ interface DurableModuleAsyncOptions {
 declare class DurableModule {
     static forRoot(options: DurableModuleOptions): DynamicModule;
     static forRootAsync(options: DurableModuleAsyncOptions): DynamicModule;
+    /**
+     * Validates role/axis constraints, in resolution order. When {@link DurableModuleOptions.topology}
+     * is set, it OWNS validation — {@link assertValidTopology}'s own store/transport/connection checks
+     * are strictly stronger than {@link assertValidRole}'s, so the topology-specific, axis-teaching
+     * message is what a `topology`-opted-in consumer sees (not the older generic one). Falls back to
+     * {@link assertValidRole} unchanged when `topology` is absent — zero behavior change.
+     */
+    private static assertValid;
     private static build;
 }
 
@@ -722,6 +804,9 @@ declare class ProxyRunGateway implements RunGateway {
     listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Round-trips to the operator, which scopes the result to this tenant's own `@<tenant>` groups. */
     workerHealth(): Promise<GroupHealth[]>;
+    /** Bulk, one request for the whole id list (like `listRuns`, not one request per id). The operator
+     *  filters the reply to runs this tenant actually owns (see `RunRequestResponder`). */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     cancel(runId: string, opts?: {
         compensate?: boolean;
     }): Promise<RunResult | null>;
@@ -810,6 +895,17 @@ declare class StoreRunGateway implements RunGateway {
     topology(): DurableTopology;
     getRunDetail(runId: string): Promise<RunDetail | null>;
     listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Bulk-resolve what each of `runIds` is currently parked on — for a consumer with its own filtered/
+     * paginated run listing (e.g. "which of MY suspended runs are stuck at a breakpoint") without
+     * re-deriving `listRuns`' waiter scan or querying `durable_step_checkpoints` directly. Mirrors
+     * `listRuns`' waiting computation (the SAME bulk signal-waiter scan + `resolveRunWaiting`), but ALSO
+     * bulk-fetches the currently-suspended runs to check real status: `engine.cancel` (the non-compensate
+     * path) doesn't clear a run's signal waiter row, so a cancelled run can leave an ORPHANED waiter
+     * behind — trusting waiter presence alone would wrongly report a terminal run as still waiting.
+     * Two bulk scans total (never one query per requested id), same as `listRuns`.
+     */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     /** Every group the engine knows about — unscoped. A tenant proxy's request is scoped by the
      *  `RunRequestResponder` (to the requester's `@<tenant>` groups); the operator's own UI sees all. */
     workerHealth(): Promise<GroupHealth[]>;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { StepError, WorkflowRef, SingletonConfig, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, GroupHealth, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, EngineEvent, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, StepCheckpoint, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowRun } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -51,6 +52,8 @@ interface WorkflowMeta {
     inputSchema?: (new (...args: any[]) => object) | undefined;
     /** Custom input validator (throws on invalid). See `WorkflowOptions`. */
     validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+    /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
+    searchAttributes?: SearchAttributesSchema | undefined;
     /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
     onEvent?: string[] | undefined;
     /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
@@ -102,6 +105,32 @@ interface WorkflowOptions {
      * `inputSchema`. Takes precedence over `inputSchema` if both are set.
      */
     validateInput?: (input: unknown) => void | Promise<void>;
+    /**
+     * Validate this workflow's {@link WorkflowCtx.upsertSearchAttributes} writes against a **Standard
+     * Schema** (https://standardschema.dev — zod 3.24+, valibot, arktype, …). `ctx.upsertSearchAttributes`
+     * validates the MERGED result (existing attributes shallow-merged with the patch) on every call —
+     * an invalid merge throws, naming this workflow, the offending key(s), and the schema's issues. The
+     * schema's inferred output must be search-attribute-shaped (flat `string`/`number`/`boolean` values
+     * only) — a schema whose output has a nested object/array is a compile-time error here. Omit for
+     * the prior unvalidated behavior.
+     *
+     * ```ts
+     * import { z } from 'zod';
+     *
+     * const orderAttrs = z.object({
+     *   tier: z.enum(['free', 'pro']),
+     *   amount: z.number(),
+     * });
+     *
+     * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+     * class CheckoutWorkflow {
+     *   async run(ctx: WorkflowCtx<InferSearchAttributes<typeof orderAttrs>>, input: CheckoutInput) {
+     *     await ctx.upsertSearchAttributes({ tier: input.tier, amount: input.total });
+     *   }
+     * }
+     * ```
+     */
+    searchAttributes?: SearchAttributesSchema;
     /**
      * Start a fresh run of this workflow whenever any of these events is published via
      * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
@@ -289,6 +318,10 @@ interface DurableRetentionOptions {
  *
  * `forRoot` throws when neither `store` nor `connection` is set, and when `store` is set without a
  * `transport`.
+ *
+ * Set {@link DurableModuleOptions.topology} to name the role explicitly instead of relying on this
+ * inference — it additionally VALIDATES the axes above (`namespace` vs `partition`) that this prose
+ * is otherwise the only source of truth for. Omitting it changes nothing.
  */
 interface DurableModuleOptions {
     /** State store — set this to play the **operator** role (see the interface doc for the full role
@@ -478,6 +511,47 @@ interface DurableModuleOptions {
     /** Timeout for a thin worker's `RunGateway` round-trip over `transport` before it rejects. Defaults
      *  to 10_000ms inside `ProxyRunGateway`. Ignored for an operator (bound to `StoreRunGateway`). */
     runGatewayTimeoutMs?: number;
+    /**
+     * An explicit preset that NAMES the deployment role instead of leaving it to `store`/`connection`
+     * inference, and VALIDATES the axes that are otherwise only prose (see the interface doc's role
+     * matrix, and {@link namespace} vs {@link partition}). Omit to keep the existing inference —
+     * `topology` is entirely additive and changes nothing when unset.
+     *
+     * **`namespace` vs `partition` — the two axes this preset locks down:**
+     * - `namespace` is the OPERATOR's poll-scoping axis: which runs a control-plane instance
+     *   drives/recovers/resumes (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`).
+     *   Unset makes the instance see (drive) EVERY namespace.
+     *   `{ role: 'control-plane' }` is the only preset that allows it.
+     * - `partition` is the WORKER's queue-routing suffix: which queue a thin/co-located worker's
+     *   consumer subscribes to (`<name>@<partition>`), matching the queue an operator's convention
+     *   dispatch routes a run's `namespace` to. `{ role: 'tenant' }` sets this FOR you from `tenant` —
+     *   you never set `partition` directly under `topology`.
+     *
+     * ```ts
+     * // Control plane: owns the store, dispatches over the transport, prunes old runs.
+     * DurableModule.forRoot({
+     *   topology: { role: 'control-plane' },
+     *   store,
+     *   transport,
+     *   retention: { policies: [{ statuses: ['completed', 'cancelled'], maxAge: '14d' }] },
+     * });
+     *
+     * // Tenant: store-less worker scoped to its own partition — `tenant` maps to `partition` for you.
+     * DurableModule.forRoot({
+     *   topology: { role: 'tenant', tenant: 'acme-corp' },
+     *   connection: process.env.REDIS_URL,
+     * });
+     * ```
+     *
+     * Validated at `forRoot`/`forRootAsync` resolution time — see {@link DurableModule} for the exact
+     * error messages, which double as the axis primer above.
+     */
+    topology?: {
+        role: 'control-plane';
+    } | {
+        role: 'tenant';
+        tenant: string;
+    };
 }
 interface DurableModuleAsyncOptions {
     useFactory: (...args: never[]) => DurableModuleOptions | Promise<DurableModuleOptions>;
@@ -486,6 +560,14 @@ interface DurableModuleAsyncOptions {
 declare class DurableModule {
     static forRoot(options: DurableModuleOptions): DynamicModule;
     static forRootAsync(options: DurableModuleAsyncOptions): DynamicModule;
+    /**
+     * Validates role/axis constraints, in resolution order. When {@link DurableModuleOptions.topology}
+     * is set, it OWNS validation — {@link assertValidTopology}'s own store/transport/connection checks
+     * are strictly stronger than {@link assertValidRole}'s, so the topology-specific, axis-teaching
+     * message is what a `topology`-opted-in consumer sees (not the older generic one). Falls back to
+     * {@link assertValidRole} unchanged when `topology` is absent — zero behavior change.
+     */
+    private static assertValid;
     private static build;
 }
 
@@ -722,6 +804,9 @@ declare class ProxyRunGateway implements RunGateway {
     listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Round-trips to the operator, which scopes the result to this tenant's own `@<tenant>` groups. */
     workerHealth(): Promise<GroupHealth[]>;
+    /** Bulk, one request for the whole id list (like `listRuns`, not one request per id). The operator
+     *  filters the reply to runs this tenant actually owns (see `RunRequestResponder`). */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     cancel(runId: string, opts?: {
         compensate?: boolean;
     }): Promise<RunResult | null>;
@@ -810,6 +895,17 @@ declare class StoreRunGateway implements RunGateway {
     topology(): DurableTopology;
     getRunDetail(runId: string): Promise<RunDetail | null>;
     listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Bulk-resolve what each of `runIds` is currently parked on — for a consumer with its own filtered/
+     * paginated run listing (e.g. "which of MY suspended runs are stuck at a breakpoint") without
+     * re-deriving `listRuns`' waiter scan or querying `durable_step_checkpoints` directly. Mirrors
+     * `listRuns`' waiting computation (the SAME bulk signal-waiter scan + `resolveRunWaiting`), but ALSO
+     * bulk-fetches the currently-suspended runs to check real status: `engine.cancel` (the non-compensate
+     * path) doesn't clear a run's signal waiter row, so a cancelled run can leave an ORPHANED waiter
+     * behind — trusting waiter presence alone would wrongly report a terminal run as still waiting.
+     * Two bulk scans total (never one query per requested id), same as `listRuns`.
+     */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     /** Every group the engine knows about — unscoped. A tenant proxy's request is scoped by the
      *  `RunRequestResponder` (to the requester's `@<tenant>` groups); the operator's own UI sees all. */
     workerHealth(): Promise<GroupHealth[]>;

package/dist/index.js

@@ -22,6 +22,7 @@ function Workflow(options) {
       executionTimeout: options.executionTimeout,
       inputSchema: options.inputSchema,
       validateInput: options.validateInput,
+      searchAttributes: options.searchAttributes,
       onEvent: options.onEvent,
       debounce: options.debounce,
       batch: options.batch
@@ -436,6 +437,9 @@ function unavailableRunGateway() {
     listRuns(_query) {
       return tenantGatewayUnavailable("listRuns");
     },
+    waitingFor(_runIds) {
+      return tenantGatewayUnavailable("waitingFor");
+    },
     workerHealth() {
       return tenantGatewayUnavailable("workerHealth");
     },
@@ -853,6 +857,14 @@ var ProxyRunGateway = class {
       kind: "workerHealth"
     });
   }
+  /** Bulk, one request for the whole id list (like `listRuns`, not one request per id). The operator
+  *  filters the reply to runs this tenant actually owns (see `RunRequestResponder`). */
+  waitingFor(runIds) {
+    return this.request({
+      kind: "waitingFor",
+      runIds
+    });
+  }
   cancel(runId, opts) {
     return this.request(opts === void 0 ? {
       kind: "cancel",
@@ -1066,6 +1078,27 @@ var RunRequestResponder = class {
         }
       };
     }
+    if (body.kind === "waitingFor") {
+      const all = await this.gateway.waitingFor(body.runIds);
+      const owned = await Promise.all(Object.entries(all).map(async ([runId, waiting]) => {
+        const runDetail = await this.gateway.getRunDetail(runId);
+        return runDetail && runDetail.run.namespace === msg.tenant ? [
+          runId,
+          waiting
+        ] : void 0;
+      }));
+      const data = {};
+      for (const entry of owned) {
+        if (entry) data[entry[0]] = entry[1];
+      }
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
     const detail = await this.gateway.getRunDetail(body.runId);
     if (detail && detail.run.namespace !== msg.tenant) {
       return {
@@ -1184,6 +1217,36 @@ var StoreRunGateway = class {
       } : run;
     });
   }
+  /**
+  * Bulk-resolve what each of `runIds` is currently parked on — for a consumer with its own filtered/
+  * paginated run listing (e.g. "which of MY suspended runs are stuck at a breakpoint") without
+  * re-deriving `listRuns`' waiter scan or querying `durable_step_checkpoints` directly. Mirrors
+  * `listRuns`' waiting computation (the SAME bulk signal-waiter scan + `resolveRunWaiting`), but ALSO
+  * bulk-fetches the currently-suspended runs to check real status: `engine.cancel` (the non-compensate
+  * path) doesn't clear a run's signal waiter row, so a cancelled run can leave an ORPHANED waiter
+  * behind — trusting waiter presence alone would wrongly report a terminal run as still waiting.
+  * Two bulk scans total (never one query per requested id), same as `listRuns`.
+  */
+  async waitingFor(runIds) {
+    if (runIds.length === 0) return {};
+    const idSet = new Set(runIds);
+    const [suspended, waiters] = await Promise.all([
+      this.store.listRuns({
+        statuses: [
+          "suspended"
+        ]
+      }),
+      this.store.listSignalWaiters("")
+    ]);
+    const waiterByRun = indexWaitersByRun(waiters);
+    const result = {};
+    for (const run of suspended) {
+      if (!idSet.has(run.id)) continue;
+      const waiting = resolveRunWaiting(run, waiterByRun);
+      if (waiting) result[run.id] = waiting;
+    }
+    return result;
+  }
   /** Every group the engine knows about — unscoped. A tenant proxy's request is scoped by the
   *  `RunRequestResponder` (to the requester's `@<tenant>` groups); the operator's own UI sees all. */
   workerHealth() {
@@ -1475,6 +1538,7 @@ var WorkflowRegistrar = class {
         singleton: meta.singleton,
         executionTimeout: meta.executionTimeout,
         validateInput,
+        searchAttributesSchema: meta.searchAttributes,
         onEvent: getOnEvents(meta, workflowCtor),
         eventBatch,
         // Uniform dispatch (opt-in): when an in-app worker is configured, register the body GROUP-SERVED
@@ -1707,6 +1771,47 @@ function assertValidRole(options) {
   }
 }
 __name(assertValidRole, "assertValidRole");
+function assertValidTopology(options) {
+  const topology = options.topology;
+  if (topology === void 0) return;
+  if (topology.role === "control-plane") {
+    if (options.store === void 0 || options.transport === void 0 && options.transports === void 0) {
+      throw new Error("topology: { role: 'control-plane' } needs `store` AND (`transport` or `transports`).\nA control-plane node is the durable operator: it owns the state store and dispatches runs to workers over a transport \u2014 without both, there is nothing for it to operate.");
+    }
+    if (options.partition !== void 0) {
+      throw new Error("topology: { role: 'control-plane' } forbids `partition`.\npartition is the WORKER queue-routing suffix \u2014 on a control-plane node, runs are dispatched to tenant partitions via each run's namespace, not via this option. Set `partition` (or `topology: { role: 'tenant', tenant }`) on the WORKER node instead.");
+    }
+    if ("tenant" in topology) {
+      throw new Error("topology: { role: 'control-plane' } forbids a `tenant` field.\ntenant names a WORKER's isolation partition \u2014 a control-plane node serves every tenant's runs (via their namespace), it isn't scoped to one itself.");
+    }
+    return;
+  }
+  if (options.connection === void 0) {
+    throw new Error(`topology: { role: 'tenant', tenant: '${topology.tenant}' } needs \`connection\`.
+A tenant is a store-less worker: it connects to the broker directly to pull its own partition of tasks instead of polling a store it does not have.`);
+  }
+  if (options.store !== void 0) {
+    throw new Error("topology: { role: 'tenant' } forbids `store`.\nA tenant is store-less BY DEFINITION \u2014 a `store` present means you actually wanted `topology: { role: 'control-plane' }` (the store-owning role).");
+  }
+  if (options.namespace !== void 0) {
+    throw new Error("topology: { role: 'tenant' } forbids `namespace`.\nnamespace is the OPERATOR's poll-scoping axis (which runs a control-plane instance drives/recovers/resumes) \u2014 a tenant worker has no poll loop for it to scope. Use this preset's `tenant` field for the worker's own routing axis instead.");
+  }
+  if (options.partition !== void 0 && options.partition !== topology.tenant) {
+    throw new Error(`topology: { role: 'tenant', tenant: '${topology.tenant}' } conflicts with \`partition: '${options.partition}'\`.
+tenant maps 1:1 onto partition (the worker queue-routing suffix) \u2014 set only \`tenant\`, or set \`partition\` to the same value.`);
+  }
+}
+__name(assertValidTopology, "assertValidTopology");
+function resolveTopology(options) {
+  const topology = options.topology;
+  if (topology === void 0 || topology.role !== "tenant") return options;
+  if (options.partition !== void 0) return options;
+  return {
+    ...options,
+    partition: topology.tenant
+  };
+}
+__name(resolveTopology, "resolveTopology");
 var RunGatewayBootstrap = class RunGatewayBootstrap2 {
   static {
     __name(this, "RunGatewayBootstrap");
@@ -1767,10 +1872,10 @@ var DurableModule = class _DurableModule {
     __name(this, "DurableModule");
   }
   static forRoot(options) {
-    assertValidRole(options);
+    _DurableModule.assertValid(options);
     return _DurableModule.build({
       provide: DURABLE_OPTIONS_CANONICAL7,
-      useValue: options
+      useValue: resolveTopology(options)
     });
   }
   static forRootAsync(options) {
@@ -1778,12 +1883,26 @@ var DurableModule = class _DurableModule {
       provide: DURABLE_OPTIONS_CANONICAL7,
       useFactory: /* @__PURE__ */ __name(async (...args) => {
         const resolved = await options.useFactory(...args);
-        assertValidRole(resolved);
-        return resolved;
+        _DurableModule.assertValid(resolved);
+        return resolveTopology(resolved);
       }, "useFactory"),
       inject: options.inject ?? []
     });
   }
+  /**
+  * Validates role/axis constraints, in resolution order. When {@link DurableModuleOptions.topology}
+  * is set, it OWNS validation — {@link assertValidTopology}'s own store/transport/connection checks
+  * are strictly stronger than {@link assertValidRole}'s, so the topology-specific, axis-teaching
+  * message is what a `topology`-opted-in consumer sees (not the older generic one). Falls back to
+  * {@link assertValidRole} unchanged when `topology` is absent — zero behavior change.
+  */
+  static assertValid(options) {
+    if (options.topology !== void 0) {
+      assertValidTopology(options);
+      return;
+    }
+    assertValidRole(options);
+  }
   static build(optionsProvider) {
     return {
       module: _DurableModule,
@@ -1925,6 +2044,9 @@ var DurableModule = class _DurableModule {
 DurableModule = _ts_decorate12([
   Module({})
 ], DurableModule);
+
+// src/index.ts
+import { WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
 export {
   CONTEXT_ACCESSOR,
   DEAD_LETTER_METADATA,
@@ -1961,6 +2083,7 @@ export {
   ThinWorkflowRegistrar,
   WORKFLOW_METADATA,
   Workflow,
+  WorkflowEngine7 as WorkflowEngine,
   WorkflowService,
   entityConfigFor,
   getDurableStepMeta,