@dudousxd/nestjs-durable 0.48.2 → 0.50.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
 export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
@@ -102,6 +102,17 @@ interface ContextAccessor {
     get(): ContextStore | undefined;
 }
 
+/** A class-validator DTO class — validated with the same `plainToInstance` + `validate` NestJS's
+ *  `ValidationPipe` runs. */
+type DtoClass = new (...args: any[]) => object;
+/**
+ * What `@Workflow({ input, output })` and `@Step({ input, output })` accept: a **Standard Schema**
+ * (https://standardschema.dev — zod 3.24+, valibot, arktype, …) or a **class-validator DTO class**.
+ * The two are told apart at runtime: a value with a `~standard` property is a Standard Schema, a
+ * constructor is a DTO. A zod schema older than 3.24 (no `~standard`) still works through its `parse`.
+ */
+type IoSchema = StandardSchemaV1 | DtoClass | z.ZodType;
+
 declare const WORKFLOW_METADATA: unique symbol;
 interface WorkflowMeta {
     name: string;
@@ -121,8 +132,11 @@ interface WorkflowMeta {
     concurrency?: ConcurrencyConfig | undefined;
     /** Max wall-clock lifetime before a run is cancelled (e.g. `'2h'`). See `WorkflowOptions`. */
     executionTimeout?: string | number | undefined;
-    /** class-validator DTO validated at start. See `WorkflowOptions`. */
-    inputSchema?: (new (...args: any[]) => object) | undefined;
+    /** Input schema (Standard Schema or DTO class), parsed at start and before every turn. Holds
+     *  `input` or its `inputSchema` alias. See `WorkflowOptions`. */
+    input?: IoSchema | undefined;
+    /** Output schema, parsed before the run completes. See `WorkflowOptions`. */
+    output?: IoSchema | undefined;
     /** Custom input validator (throws on invalid). See `WorkflowOptions`. */
     validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
     /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
@@ -183,9 +197,11 @@ interface WorkflowOptions {
      */
     concurrency?: ConcurrencyConfig;
     /**
-     * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms). A run that
-     * outlives it is moved to `cancelled` (`execution_timeout`) by the timer poller — a backstop for
-     * runs that get stuck or loop forever. Omit for no limit.
+     * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms), counted from
+     * the run's creation. A run that outlives it is moved to `cancelled` (`execution_timeout`) by the
+     * timer poller — whether it is `pending`, `blocked`, `running` or `suspended` — a backstop for runs
+     * that get stuck, loop forever or are never picked up. A run in `cancelling` finishes its saga undo
+     * instead. Omit for no limit.
      */
     executionTimeout?: string | number;
     /**
@@ -197,15 +213,36 @@ interface WorkflowOptions {
      */
     requires?: string[];
     /**
-     * Validate the workflow input at `start` against a **class-validator DTO** (the same
-     * `plainToInstance` + `validate` NestJS runs in controllers) — invalid input is rejected before any
-     * run is created. Needs the optional peers `class-validator` + `class-transformer`.
-     * `@Workflow({ inputSchema: CheckoutInput })`.
+     * The run's input schema — a **Standard Schema** (zod 3.24+, valibot, arktype, …) or a
+     * **class-validator DTO class** (the same `plainToInstance` + `validate` NestJS's `ValidationPipe`
+     * runs; needs the optional peers `class-validator` + `class-transformer`). The same option
+     * `@Step({ input })` takes.
+     *
+     * Parsed at `start`, so invalid input is rejected before any run is created. The run stores the
+     * input **as it was sent**; `run(ctx, input)` receives the **parsed** value (coerced/transformed —
+     * a `Date` from `z.coerce.date()`, a DTO instance), re-parsed from the stored input before every
+     * turn, so a replay sees the same value the first execution did. The schema must therefore be
+     * deterministic (no `default(() => Date.now())`), and changing it is a breaking change to the
+     * workflow — bump `version`. A stored input that no longer parses fails the run with
+     * `code: 'invalid_input'`.
+     *
+     * `@Workflow({ name: 'checkout', input: CheckoutInput })` or `input: z.object({ … })`.
+     */
+    input?: IoSchema;
+    /**
+     * The run's output schema (same forms as {@link input}). The value `run()` returns is parsed before
+     * the run completes, and the parsed value is what the run stores as its output. A mismatch fails the
+     * run with `code: 'invalid_output'`. The same option `@Step({ output })` takes.
      */
-    inputSchema?: new (...args: any[]) => object;
+    output?: IoSchema;
     /**
-     * Custom input validator (throws on invalid) — an escape hatch for zod/yup/etc. instead of
-     * `inputSchema`. Takes precedence over `inputSchema` if both are set.
+     * Alias of {@link input}, kept for workflows declared before `input` existed. Setting both is an
+     * error.
+     */
+    inputSchema?: IoSchema;
+    /**
+     * A custom check at `start` (throw to reject) for a rule a schema can't express — a cross-field
+     * invariant, an async lookup. It sees the input as it was sent, and runs after `input` parses.
      */
     validateInput?: (input: unknown) => void | Promise<void>;
     /**
@@ -268,9 +305,9 @@ interface DurableStepMeta {
     name: string;
     /** Opt-in runtime input schema, validated when the handler is served (see `scanSteps`). Absent on
      *  a bare `@Step()` — compile-time types from the method signature only, no runtime check. */
-    input?: z.ZodType | undefined;
+    input?: IoSchema | undefined;
     /** Opt-in runtime output schema, validated before the handler's result is handed back. */
-    output?: z.ZodType | undefined;
+    output?: IoSchema | undefined;
 }
 /**
  * `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?, backoffMaxMs?, jitter?,
@@ -279,10 +316,12 @@ interface DurableStepMeta {
 interface StepOptions {
     /** Explicit routing name, overriding the derived `Class.method`. */
     name?: string;
-    /** Runtime input schema, validated at the serve boundary (opt-in — a bare `@Step()` skips it). */
-    input?: z.ZodType;
+    /** Runtime input schema, validated at the serve boundary (opt-in — a bare `@Step()` skips it). A
+     *  Standard Schema (zod, valibot, …) or a class-validator DTO class — the same forms
+     *  `@Workflow({ input })` takes. The method receives the parsed value. */
+    input?: IoSchema;
     /** Runtime output schema, validated before the result is returned (opt-in). */
-    output?: z.ZodType;
+    output?: IoSchema;
     /**
      * Def-level durable-dispatch policy stamped under `DURABLE_STEP_CONFIG` and read by `ctx.step` at
      * the dispatch boundary (see `stepConfigOf`) — a per-call `ctx.step(ref, input, opts)` overrides
@@ -328,8 +367,8 @@ interface StepOptions {
  * - `@Step('custom:name')` — explicit name override (stable across refactors, or a cross-runtime
  *   contract with a non-JS worker that has no `@Step` of its own).
  * - `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?, backoffMaxMs?, jitter?,
- *   timeoutMs? })` — optional name override, opt-in RUNTIME zod schemas, and a def-level
- *   durable-retry/liveness-timeout policy. `input` validates before the method runs; `output`
+ *   timeoutMs? })` — optional name override, opt-in RUNTIME schemas (a Standard Schema or a DTO
+ *   class), and a def-level durable-retry/liveness-timeout policy. `input` validates before the method runs; `output`
  *   validates its return value before it's handed back (see `scanSteps`). `retries`/`backoff`/
  *   `backoffMs`/`backoffMaxMs`/`jitter`/`timeoutMs` are the policy `ctx.step` reads off this method
  *   reference (via `stepConfigOf`) to build the dispatched `StepDef`'s durable retry/backoff and
@@ -558,6 +597,19 @@ interface DurableModuleOptions {
      * See `WorkflowEngineDeps.reconcileMs`. Operator only.
      */
     reconcileMs?: number;
+    /**
+     * Idle time (ms) before a stranded in-flight run is reported to {@link onStalled} listeners.
+     * Defaults to 900000 (15 min), floored at 60000. See `WorkflowEngineDeps.stalledAfterMs`.
+     * Operator only.
+     */
+    stalledAfterMs?: number;
+    /**
+     * Pager hook for stranded runs, registered on the engine as `engine.onStalled(...)`: a run
+     * suspended with no wake timer, or parked on an old pending remote step nothing is leasing. The
+     * timer poller sweeps once a minute and reports each stranded episode once per instance.
+     * Equivalent to calling `engine.onStalled` from a provider; only a DRIVING operator sweeps.
+     */
+    onStalled?: (info: StalledRunInfo) => void;
     /**
      * The most due timers one timer-poll pass loads and drives, most overdue first, so a wave of
      * thousands of due runs is worked through in batches. Defaults to 500; a non-finite or sub-1 value
@@ -1321,4 +1373,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
 export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
@@ -102,6 +102,17 @@ interface ContextAccessor {
     get(): ContextStore | undefined;
 }
 
+/** A class-validator DTO class — validated with the same `plainToInstance` + `validate` NestJS's
+ *  `ValidationPipe` runs. */
+type DtoClass = new (...args: any[]) => object;
+/**
+ * What `@Workflow({ input, output })` and `@Step({ input, output })` accept: a **Standard Schema**
+ * (https://standardschema.dev — zod 3.24+, valibot, arktype, …) or a **class-validator DTO class**.
+ * The two are told apart at runtime: a value with a `~standard` property is a Standard Schema, a
+ * constructor is a DTO. A zod schema older than 3.24 (no `~standard`) still works through its `parse`.
+ */
+type IoSchema = StandardSchemaV1 | DtoClass | z.ZodType;
+
 declare const WORKFLOW_METADATA: unique symbol;
 interface WorkflowMeta {
     name: string;
@@ -121,8 +132,11 @@ interface WorkflowMeta {
     concurrency?: ConcurrencyConfig | undefined;
     /** Max wall-clock lifetime before a run is cancelled (e.g. `'2h'`). See `WorkflowOptions`. */
     executionTimeout?: string | number | undefined;
-    /** class-validator DTO validated at start. See `WorkflowOptions`. */
-    inputSchema?: (new (...args: any[]) => object) | undefined;
+    /** Input schema (Standard Schema or DTO class), parsed at start and before every turn. Holds
+     *  `input` or its `inputSchema` alias. See `WorkflowOptions`. */
+    input?: IoSchema | undefined;
+    /** Output schema, parsed before the run completes. See `WorkflowOptions`. */
+    output?: IoSchema | undefined;
     /** Custom input validator (throws on invalid). See `WorkflowOptions`. */
     validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
     /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
@@ -183,9 +197,11 @@ interface WorkflowOptions {
      */
     concurrency?: ConcurrencyConfig;
     /**
-     * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms). A run that
-     * outlives it is moved to `cancelled` (`execution_timeout`) by the timer poller — a backstop for
-     * runs that get stuck or loop forever. Omit for no limit.
+     * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms), counted from
+     * the run's creation. A run that outlives it is moved to `cancelled` (`execution_timeout`) by the
+     * timer poller — whether it is `pending`, `blocked`, `running` or `suspended` — a backstop for runs
+     * that get stuck, loop forever or are never picked up. A run in `cancelling` finishes its saga undo
+     * instead. Omit for no limit.
      */
     executionTimeout?: string | number;
     /**
@@ -197,15 +213,36 @@ interface WorkflowOptions {
      */
     requires?: string[];
     /**
-     * Validate the workflow input at `start` against a **class-validator DTO** (the same
-     * `plainToInstance` + `validate` NestJS runs in controllers) — invalid input is rejected before any
-     * run is created. Needs the optional peers `class-validator` + `class-transformer`.
-     * `@Workflow({ inputSchema: CheckoutInput })`.
+     * The run's input schema — a **Standard Schema** (zod 3.24+, valibot, arktype, …) or a
+     * **class-validator DTO class** (the same `plainToInstance` + `validate` NestJS's `ValidationPipe`
+     * runs; needs the optional peers `class-validator` + `class-transformer`). The same option
+     * `@Step({ input })` takes.
+     *
+     * Parsed at `start`, so invalid input is rejected before any run is created. The run stores the
+     * input **as it was sent**; `run(ctx, input)` receives the **parsed** value (coerced/transformed —
+     * a `Date` from `z.coerce.date()`, a DTO instance), re-parsed from the stored input before every
+     * turn, so a replay sees the same value the first execution did. The schema must therefore be
+     * deterministic (no `default(() => Date.now())`), and changing it is a breaking change to the
+     * workflow — bump `version`. A stored input that no longer parses fails the run with
+     * `code: 'invalid_input'`.
+     *
+     * `@Workflow({ name: 'checkout', input: CheckoutInput })` or `input: z.object({ … })`.
+     */
+    input?: IoSchema;
+    /**
+     * The run's output schema (same forms as {@link input}). The value `run()` returns is parsed before
+     * the run completes, and the parsed value is what the run stores as its output. A mismatch fails the
+     * run with `code: 'invalid_output'`. The same option `@Step({ output })` takes.
      */
-    inputSchema?: new (...args: any[]) => object;
+    output?: IoSchema;
     /**
-     * Custom input validator (throws on invalid) — an escape hatch for zod/yup/etc. instead of
-     * `inputSchema`. Takes precedence over `inputSchema` if both are set.
+     * Alias of {@link input}, kept for workflows declared before `input` existed. Setting both is an
+     * error.
+     */
+    inputSchema?: IoSchema;
+    /**
+     * A custom check at `start` (throw to reject) for a rule a schema can't express — a cross-field
+     * invariant, an async lookup. It sees the input as it was sent, and runs after `input` parses.
      */
     validateInput?: (input: unknown) => void | Promise<void>;
     /**
@@ -268,9 +305,9 @@ interface DurableStepMeta {
     name: string;
     /** Opt-in runtime input schema, validated when the handler is served (see `scanSteps`). Absent on
      *  a bare `@Step()` — compile-time types from the method signature only, no runtime check. */
-    input?: z.ZodType | undefined;
+    input?: IoSchema | undefined;
     /** Opt-in runtime output schema, validated before the handler's result is handed back. */
-    output?: z.ZodType | undefined;
+    output?: IoSchema | undefined;
 }
 /**
  * `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?, backoffMaxMs?, jitter?,
@@ -279,10 +316,12 @@ interface DurableStepMeta {
 interface StepOptions {
     /** Explicit routing name, overriding the derived `Class.method`. */
     name?: string;
-    /** Runtime input schema, validated at the serve boundary (opt-in — a bare `@Step()` skips it). */
-    input?: z.ZodType;
+    /** Runtime input schema, validated at the serve boundary (opt-in — a bare `@Step()` skips it). A
+     *  Standard Schema (zod, valibot, …) or a class-validator DTO class — the same forms
+     *  `@Workflow({ input })` takes. The method receives the parsed value. */
+    input?: IoSchema;
     /** Runtime output schema, validated before the result is returned (opt-in). */
-    output?: z.ZodType;
+    output?: IoSchema;
     /**
      * Def-level durable-dispatch policy stamped under `DURABLE_STEP_CONFIG` and read by `ctx.step` at
      * the dispatch boundary (see `stepConfigOf`) — a per-call `ctx.step(ref, input, opts)` overrides
@@ -328,8 +367,8 @@ interface StepOptions {
  * - `@Step('custom:name')` — explicit name override (stable across refactors, or a cross-runtime
  *   contract with a non-JS worker that has no `@Step` of its own).
  * - `@Step({ name?, input?, output?, retries?, backoff?, backoffMs?, backoffMaxMs?, jitter?,
- *   timeoutMs? })` — optional name override, opt-in RUNTIME zod schemas, and a def-level
- *   durable-retry/liveness-timeout policy. `input` validates before the method runs; `output`
+ *   timeoutMs? })` — optional name override, opt-in RUNTIME schemas (a Standard Schema or a DTO
+ *   class), and a def-level durable-retry/liveness-timeout policy. `input` validates before the method runs; `output`
  *   validates its return value before it's handed back (see `scanSteps`). `retries`/`backoff`/
  *   `backoffMs`/`backoffMaxMs`/`jitter`/`timeoutMs` are the policy `ctx.step` reads off this method
  *   reference (via `stepConfigOf`) to build the dispatched `StepDef`'s durable retry/backoff and
@@ -558,6 +597,19 @@ interface DurableModuleOptions {
      * See `WorkflowEngineDeps.reconcileMs`. Operator only.
      */
     reconcileMs?: number;
+    /**
+     * Idle time (ms) before a stranded in-flight run is reported to {@link onStalled} listeners.
+     * Defaults to 900000 (15 min), floored at 60000. See `WorkflowEngineDeps.stalledAfterMs`.
+     * Operator only.
+     */
+    stalledAfterMs?: number;
+    /**
+     * Pager hook for stranded runs, registered on the engine as `engine.onStalled(...)`: a run
+     * suspended with no wake timer, or parked on an old pending remote step nothing is leasing. The
+     * timer poller sweeps once a minute and reports each stranded episode once per instance.
+     * Equivalent to calling `engine.onStalled` from a provider; only a DRIVING operator sweeps.
+     */
+    onStalled?: (info: StalledRunInfo) => void;
     /**
      * The most due timers one timer-poll pass loads and drives, most overdue first, so a wave of
      * thousands of due runs is worked through in batches. Defaults to 500; a non-finite or sub-1 value
@@ -1321,4 +1373,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };

package/dist/index.js

@@ -119,6 +119,9 @@ __name(fileOfFrame, "fileOfFrame");
 var WORKFLOW_METADATA = Symbol("nestjs-durable:workflow");
 function Workflow(options) {
   const declaredIn = declaringFile(Workflow);
+  if (options.input !== void 0 && options.inputSchema !== void 0) {
+    throw new Error(`@Workflow ${options.name}: set either \`input\` or its alias \`inputSchema\`, not both`);
+  }
   return (target) => {
     rememberDeclaringFile(target, declaredIn);
     const meta = {
@@ -130,7 +133,8 @@ function Workflow(options) {
       singleton: options.singleton,
       concurrency: options.concurrency,
       executionTimeout: options.executionTimeout,
-      inputSchema: options.inputSchema,
+      input: options.input ?? options.inputSchema,
+      output: options.output,
       validateInput: options.validateInput,
       searchAttributes: options.searchAttributes,
       onEvent: options.onEvent,
@@ -388,6 +392,94 @@ import { DURABLE_OPTIONS_CANONICAL } from "@dudousxd/nestjs-durable-core";
 import { Inject, Injectable as Injectable2 } from "@nestjs/common";
 import { DiscoveryService, MetadataScanner } from "@nestjs/core";
 
+// src/schema-parse.ts
+import { FatalError } from "@dudousxd/nestjs-durable-core";
+function schemaParser(schema, kind, label) {
+  const code = kind === "input" ? "invalid_input" : "invalid_output";
+  if (isStandardSchema(schema)) {
+    return async (value) => {
+      const result = await schema["~standard"].validate(value);
+      if (result.issues) {
+        const issues = result.issues.map((i) => ({
+          message: i.message,
+          ...i.path ? {
+            path: i.path.map((p) => String(typeof p === "object" ? p.key : p))
+          } : {}
+        }));
+        throw new FatalError(`invalid ${label}: ${formatIssues(issues)}`, code, issues);
+      }
+      return result.value;
+    };
+  }
+  if (isZodLike(schema)) {
+    return async (value) => {
+      const result = schema.safeParse(value);
+      if (!result.success) {
+        const issues = result.error.issues.map((i) => ({
+          message: i.message,
+          path: i.path.map(String)
+        }));
+        throw new FatalError(`invalid ${label}: ${formatIssues(issues)}`, code, issues);
+      }
+      return result.data;
+    };
+  }
+  if (typeof schema === "function") return classValidatorParser(schema, code, label);
+  throw new Error(`${label}: expected a Standard Schema (zod, valibot, \u2026) or a class-validator DTO class`);
+}
+__name(schemaParser, "schemaParser");
+function classValidatorParser(cls, code, label) {
+  return async (value) => {
+    let cv;
+    let ct;
+    try {
+      cv = await import("class-validator");
+      ct = await import("class-transformer");
+    } catch {
+      throw new Error(`${label} uses a class-validator DTO, which needs the optional peers "class-validator" and "class-transformer" \u2014 install them, or use a Standard Schema (zod, valibot, \u2026) instead.`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      const got = value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
+      const message = `expected an object, got ${got}`;
+      throw new FatalError(`invalid ${label}: ${message}`, code, [
+        {
+          message
+        }
+      ]);
+    }
+    const instance = ct.plainToInstance(cls, value);
+    const errors = await cv.validate(instance, {
+      whitelist: true
+    });
+    if (errors.length > 0) {
+      const issues = errors.map((e) => ({
+        message: Object.values(e.constraints ?? {
+          _: `${e.property} is invalid`
+        }).join(", "),
+        path: [
+          String(e.property)
+        ]
+      }));
+      const message = issues.map((i) => i.message).join("; ");
+      throw new FatalError(`invalid ${label}: ${message}`, code, issues);
+    }
+    return instance;
+  };
+}
+__name(classValidatorParser, "classValidatorParser");
+function isStandardSchema(schema) {
+  return (typeof schema === "object" || typeof schema === "function") && schema !== null && "~standard" in schema;
+}
+__name(isStandardSchema, "isStandardSchema");
+function isZodLike(schema) {
+  return typeof schema === "object" && schema !== null && typeof schema.safeParse === "function";
+}
+__name(isZodLike, "isZodLike");
+function formatIssues(issues) {
+  return issues.map((i) => i.path && i.path.length > 0 ? `${i.path.join(".")}: ${i.message}` : i.message).join("; ");
+}
+__name(formatIssues, "formatIssues");
+
 // src/discovery-helpers.ts
 function scanWorkflows(discovery, register) {
   for (const wrapper of discovery.getProviders()) {
@@ -414,10 +506,12 @@ function scanSteps(discovery, scanner, register) {
       const meta = getDurableStepMeta(method);
       if (!meta) continue;
       const boundMethod = method;
+      const parseInput = meta.input && schemaParser(meta.input, "input", `step "${meta.name}" input`);
+      const parseOutput = meta.output && schemaParser(meta.output, "output", `step "${meta.name}" output`);
       const handler = /* @__PURE__ */ __name(async (input, log) => {
-        const validInput = meta.input ? meta.input.parse(input) : input;
+        const validInput = parseInput ? await parseInput(input) : input;
         const output = await boundMethod.call(instance, validInput, log);
-        return meta.output ? meta.output.parse(output) : output;
+        return parseOutput ? parseOutput(output) : output;
       }, "handler");
       register(meta, handler);
     }
@@ -457,6 +551,24 @@ function onErrorHandlersOf(meta, instance, scanner) {
 }
 __name(onErrorHandlersOf, "onErrorHandlersOf");
 
+// src/workflow-io.ts
+function workflowIo(meta) {
+  const parseInput = meta.input && schemaParser(meta.input, "input", `workflow "${meta.name}" input`);
+  const parseOutput = meta.output && schemaParser(meta.output, "output", `workflow "${meta.name}" output`);
+  const validateInput = meta.validateInput;
+  return {
+    validateAtStart: parseInput || validateInput ? async (input) => {
+      if (parseInput) await parseInput(input);
+      await validateInput?.(input);
+    } : void 0,
+    wrap: /* @__PURE__ */ __name((body) => !parseInput && !parseOutput ? body : async (ctx, input) => {
+      const output = await body(ctx, parseInput ? await parseInput(input) : input);
+      return parseOutput ? parseOutput(output) : output;
+    }, "wrap")
+  };
+}
+__name(workflowIo, "workflowIo");
+
 // src/runtime-registration.ts
 function registerOnRuntime(runtime, scanner, meta, instance, origin) {
   const { handlers, routes } = onErrorHandlersOf(meta, instance, scanner);
@@ -466,7 +578,8 @@ function registerOnRuntime(runtime, scanner, meta, instance, origin) {
       origin
     } : {}
   };
-  runtime.registerWorkflow(meta.name, (ctx, input) => instance.run(ctx, input), {
+  const body = workflowIo(meta).wrap((ctx, input) => instance.run(ctx, input));
+  runtime.registerWorkflow(meta.name, body, {
     ...announced,
     ...meta.requires !== void 0 ? {
       requires: meta.requires
@@ -2073,6 +2186,7 @@ var TimerPoller = class {
       await this.sweep("recoverIncomplete", () => this.engine.recoverIncomplete());
       await this.sweep("resumeDueTimers", () => this.engine.resumeDueTimers());
       await this.sweep("sweepTimeouts", () => this.engine.sweepTimeouts());
+      await this.sweep("sweepStalled", async () => this.engine.sweepStalled?.());
       const schedules = this.options.schedules;
       if (schedules && schedules.length > 0) {
         await this.sweep("schedules", () => runSchedules(this.engine, schedules, Date.now()));
@@ -2111,31 +2225,6 @@ import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, RemoteWorkflow
 import { Inject as Inject7, Injectable as Injectable10 } from "@nestjs/common";
 import { DiscoveryService as DiscoveryService4, MetadataScanner as MetadataScanner4 } from "@nestjs/core";
 
-// src/input-validation.ts
-function classValidatorInput(cls) {
-  return async (input) => {
-    let cv;
-    let ct;
-    try {
-      cv = await import("class-validator");
-      ct = await import("class-transformer");
-    } catch {
-      throw new Error('@Workflow({ inputSchema }) needs the optional peers "class-validator" and "class-transformer" \u2014 install them, or pass a `validateInput` function instead.');
-    }
-    const instance = ct.plainToInstance(cls, input);
-    const errors = await cv.validate(instance, {
-      whitelist: true
-    });
-    if (errors.length > 0) {
-      const message = errors.map((e) => Object.values(e.constraints ?? {
-        _: e.property
-      }).join(", ")).join("; ");
-      throw new Error(`invalid input for workflow: ${message}`);
-    }
-  };
-}
-__name(classValidatorInput, "classValidatorInput");
-
 // src/step-interceptor.ts
 import "reflect-metadata";
 var STEP_INTERCEPTOR_METADATA = Symbol("nestjs-durable:step-interceptor");
@@ -2238,7 +2327,8 @@ var WorkflowRegistrar = class {
     const unattributed = [];
     scanWorkflows(this.discovery, (meta, workflow, origin) => {
       if (origin === void 0) unattributed.push(meta.name);
-      const validateInput = meta.validateInput ?? (meta.inputSchema ? classValidatorInput(meta.inputSchema) : void 0);
+      const io = workflowIo(meta);
+      const body = io.wrap((ctx, input) => workflow.run(ctx, input));
       const eventBatch = meta.debounce ? {
         mode: "debounce",
         windowMs: parseDuration2(meta.debounce)
@@ -2254,7 +2344,7 @@ var WorkflowRegistrar = class {
           origin
         });
       }
-      this.engine.register(meta.name, meta.version, (ctx, input) => workflow.run(ctx, input), {
+      this.engine.register(meta.name, meta.version, body, {
         // Stamped onto every run this workflow starts (see `WorkflowRun.origin`). Derived from the
         // class's declaring file, so a lib gets attributed without opting in; `undefined` when it
         // could not be derived, which the engine records as unknown rather than defaulting.
@@ -2264,7 +2354,7 @@ var WorkflowRegistrar = class {
         concurrency: meta.concurrency,
         executionTimeout: meta.executionTimeout,
         requires: meta.requires,
-        validateInput,
+        validateInput: io.validateAtStart,
         searchAttributesSchema: meta.searchAttributes,
         onEvent: getOnEvents(meta, workflowCtor),
         eventBatch,
@@ -2795,6 +2885,7 @@ var DurableModule = class _DurableModule {
               remoteRedispatchMs: options.remoteRedispatchMs,
               remoteRedispatchMax: options.remoteRedispatchMax,
               reconcileMs: options.reconcileMs,
+              stalledAfterMs: options.stalledAfterMs,
               timerBatchSize: options.timerBatchSize,
               eventBufferTtlMs: options.eventBufferTtlMs,
               blockedPollMs: options.blockedPollMs,
@@ -2818,6 +2909,7 @@ var DurableModule = class _DurableModule {
               } : void 0
             });
             for (const queue of options.queues ?? []) engine.registerQueue(queue);
+            if (options.onStalled) engine.onStalled(options.onStalled);
             return engine;
           }, "useFactory"),
           inject: [