@dudousxd/nestjs-durable-core 0.49.3 → 0.50.0

package/dist/index.d.ts

@@ -161,6 +161,74 @@ declare class InMemoryAdmissionBackend implements AdmissionBackend {
     release(queue: string, _slotId: string): Promise<void>;
 }
 
+/**
+ * Vendored subset of the Standard Schema spec (https://standardschema.dev) — the `~standard`
+ * property protocol implemented by zod 3.24+, valibot, arktype, and others. Vendored (rather than
+ * taken as a dependency) so core stays dependency-free at runtime: this file is types only, erased
+ * entirely by the build. Source: https://github.com/standard-schema/standard-schema (MIT, Colin
+ * McDonnell) — trimmed to the `StandardSchemaV1` shape this package actually consumes (drops the
+ * sibling `StandardTypedV1`/`StandardJSONSchemaV1` specs the upstream package also exports).
+ *
+ * Used to type `@Workflow({ searchAttributes })` (see `WorkflowMeta.searchAttributes` in
+ * `@dudousxd/nestjs-durable` and `SearchAttributesSchema`/`InferSearchAttributes` in `interfaces.ts`)
+ * so a workflow can declare its search-attribute shape with whatever schema library it already uses,
+ * without core taking a hard dependency on any of them.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+
 /**
  * Cross-package step-name stamp. The `@Step` decorator (`@dudousxd/nestjs-durable`) writes a
  * method's derived routing name under this key; core's `ctx.step` reads it (via {@link stepNameOf})
@@ -337,8 +405,10 @@ interface WorkflowRun {
  * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
  * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
  * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
- * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
- * signal name).
+ * ⇒ `child`, `bp:<runId>:<seq>` ⇒ `breakpoint` (a `ctx.breakpoint` DOES register a signal waiter —
+ * same machinery, `engine.continue` resumes it — so it's classified here, not left to fall through to
+ * the generic `signal` case with the raw token as its ugly display name), `event:<name>:…` ⇒ `signal`
+ * (name decoded), anything else ⇒ `signal` (the token IS the signal name).
  *
  * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
  * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
@@ -347,8 +417,13 @@ interface WorkflowRun {
  * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
  */
 interface RunWaiting {
-    on: 'signal' | 'webhook' | 'child';
-    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    on: 'signal' | 'webhook' | 'child' | 'breakpoint';
+    /**
+     * The token/name the run is parked on — the signal name, webhook token, or awaited child id. For a
+     * breakpoint this is always the literal `'breakpoint'`: the real label (if any) lives on the pending
+     * `breakpoint`/`breakpoint:<label>` checkpoint, which the detail view's timeline already shows —
+     * naming it here would need an extra per-run checkpoint read, defeating the bulk waiter scan.
+     */
     name: string;
 }
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
@@ -618,6 +693,38 @@ interface RetentionPolicy {
 }
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
+/**
+ * A Standard Schema (https://standardschema.dev — implemented by zod 3.24+, valibot, arktype, …)
+ * whose validated OUTPUT is search-attribute-shaped: flat `string`/`number`/`boolean` values only.
+ * Declared via `@Workflow({ searchAttributes })`, this makes `ctx.upsertSearchAttributes` reject any
+ * write whose merged result doesn't conform. The `Output extends SearchAttributes` bound is enforced
+ * structurally at the declaration site — a schema whose inferred output has a nested object/array
+ * value (e.g. `z.object({ meta: z.object({ ... }) })`) fails to satisfy this type, so it's a
+ * compile-time error to declare it as a `searchAttributes` schema, not a runtime surprise.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ *
+ * const orderAttrs = z.object({
+ *   tier: z.enum(['free', 'pro']),
+ *   amount: z.number(),
+ *   rushOrder: z.boolean().optional(),
+ * });
+ *
+ * @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 });
+ *   }
+ * }
+ * ```
+ */
+type SearchAttributesSchema<A extends SearchAttributes = SearchAttributes> = StandardSchemaV1<unknown, A>;
+/** Infer the validated OUTPUT shape of a {@link SearchAttributesSchema} — the typed attributes a
+ *  workflow declares via `@Workflow({ searchAttributes })`. Feed it straight into `WorkflowCtx<A>`:
+ *  `WorkflowCtx<InferSearchAttributes<typeof mySchema>>`. */
+type InferSearchAttributes<S extends StandardSchemaV1<unknown, SearchAttributes>> = StandardSchemaV1.InferOutput<S>;
 type AttributeOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
 /** One predicate over a run's {@link SearchAttributes}; a {@link RunQuery} ANDs them all. */
 interface AttributeFilter {
@@ -730,6 +837,12 @@ type RunRequestKind = {
     kind: 'retryWithInput';
     runId: string;
     input: unknown;
+} | {
+    kind: 'redispatch';
+    runId: string;
+} | {
+    kind: 'waitingFor';
+    runIds: string[];
 };
 /** The control plane's answer to a {@link RunRequest}, correlated by `requestId`. */
 interface RunReply {
@@ -1320,8 +1433,13 @@ type UndoOf<H> = H extends (input: infer I, ...rest: never[]) => infer R ? StepU
 /**
  * The context handed to a workflow function. Every interaction with the outside world goes
  * through it so the engine can checkpoint — the workflow body itself stays deterministic.
+ *
+ * Generic over `A`, the run's {@link SearchAttributes} shape — narrows {@link upsertSearchAttributes}
+ * when a workflow declares a `@Workflow({ searchAttributes })` schema (pass
+ * `WorkflowCtx<InferSearchAttributes<typeof mySchema>>` as the `run` method's ctx type). Defaults to
+ * the untyped `SearchAttributes`, so every existing `WorkflowCtx` usage is unaffected.
  */
-interface WorkflowCtx {
+interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
     readonly runId: string;
     /**
      * Run a durable step — always dispatched, always engine-scheduled: the ONE step primitive (no
@@ -1528,8 +1646,16 @@ interface WorkflowCtx {
      * write, not one per turn. Use this instead of injecting the {@link StateStore} to mutate the run
      * you're executing (`@Inject(state-store)` + `store.updateRun(ctx.runId, …)` becomes
      * `ctx.upsertSearchAttributes(…)`).
+     *
+     * When the workflow declares a `@Workflow({ searchAttributes })` schema, the MERGED result (this
+     * run's existing `searchAttributes` shallow-merged with `attrs`) is validated against it before the
+     * write — an invalid merge throws, naming the workflow, the offending key(s), and the schema's
+     * issues. Validation runs once, on the same first-run-only position as the write itself (skipped
+     * entirely on replay, so it's never a source of nondeterminism); it must be synchronous — a schema
+     * whose `validate` returns a `Promise` throws instead of being awaited. No schema declared ⇒
+     * unchanged, unvalidated behavior.
      */
-    upsertSearchAttributes(attrs: SearchAttributes): Promise<void>;
+    upsertSearchAttributes(attrs: Partial<A>): Promise<void>;
     /**
      * Run a checkpointed step **in-process** — the escape hatch from the always-dispatched {@link step}
      * for work that must run inline in the workflow body. Like `step`, its result is a durable checkpoint
@@ -1818,6 +1944,27 @@ interface WorkflowEngineDeps {
      * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
      */
     reconcileMs?: number | undefined;
+    /**
+     * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
+     * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
+     * flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
+     * checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
+     * reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
+     * worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
+     * forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
+     * re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
+     * re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
+     * longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
+     * heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
+     * survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
+     */
+    remoteRedispatchMs?: number | undefined;
+    /**
+     * Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
+     * failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
+     * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
+     */
+    remoteRedispatchMax?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1894,6 +2041,8 @@ declare class WorkflowEngine {
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
     private readonly reconcileMs;
+    private readonly remoteRedispatchMs;
+    private readonly remoteRedispatchMax;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -1983,6 +2132,8 @@ declare class WorkflowEngine {
         singleton?: SingletonConfig | undefined;
         executionTimeout?: string | number | undefined;
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
+        /** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
+        searchAttributesSchema?: SearchAttributesSchema | undefined;
         onEvent?: string[] | undefined;
         eventBatch?: EventBatchConfig | undefined;
         /** Worker group to DISPATCH this workflow's turns to (uniform dispatch). Requires `executor`.
@@ -2186,6 +2337,19 @@ declare class WorkflowEngine {
      * the HTTP request on workflow execution.
      */
     requeue(runId: string): Promise<RunResult | null>;
+    /**
+     * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
+     * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
+     * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
+     * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
+     * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+     * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
+     * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
+     * run's current status (with the count re-dispatched), or null if the run is unknown.
+     */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
     /**
      * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
      * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
@@ -2488,6 +2652,10 @@ declare class WorkflowEngine {
      */
     update(runId: string, name: string, arg: unknown): Promise<UpdateResult>;
     private callRemote;
+    /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
+     *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
+     *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
+    private dispatchRemoteTask;
     /**
      * Complete a durable remote step from its worker result and resume the run — runs on whichever
      * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
@@ -2789,7 +2957,9 @@ interface DurableTopology {
     /** The tenant's isolation partition name; set only when `role` is 'tenant'. */
     tenant?: string;
 }
-/** A run + its timeline + child ids — the detail view. Mirrors the dashboard's `RunDetail`. */
+/** A run + its timeline + child ids — the detail view. Single source of truth: the dashboard server
+ *  re-exports this instead of re-declaring it, and the dashboard client derives its wire mirror from
+ *  it via {@link WireDates} instead of hand-mirroring field by field. */
 interface RunDetail {
     run: WorkflowRun;
     /** Steps in execution order (local + remote). */
@@ -2797,6 +2967,17 @@ interface RunDetail {
     /** Ids of runs this run spawned (parent→children tree). */
     children: string[];
 }
+/**
+ * Maps every `Date` (and `Date | undefined`) field of `T` to its ISO-string wire form — the shape a
+ * JSON response actually carries once dates cross the wire (`JSON.stringify` already does this
+ * coercion; this just types it). Homomorphic: each field keeps its own optional modifier, so a
+ * required `Date` becomes a required `string` and an optional one stays optional. Lets a consumer
+ * derive its own wire-facing client type from a core server type (e.g. the dashboard's SPA `WorkflowRun`/
+ * `StepCheckpoint`/`RunDetail`) instead of hand-mirroring it field by field and drifting.
+ */
+type WireDates<T> = {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | undefined ? string | undefined : T[K];
+};
 /**
  * The bounded read/control/stream surface a consumer (e.g. a controller) needs, satisfied by BOTH
  * topologies: the control plane binds a store-backed impl (reuses `DashboardService`); a tenant binds
@@ -2812,6 +2993,17 @@ interface RunGateway {
      *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
      *  plane sent. */
     listRuns(query: RunQuery): Promise<RunListItem[]>;
+    /**
+     * Bulk-resolve {@link RunWaiting} for an arbitrary set of run ids — for a consumer with its OWN
+     * filtered/paginated run listing (so it isn't just `listRuns` under another name) that needs to know
+     * which of ITS runs are parked on a breakpoint (or any other event wait) without re-deriving the bulk
+     * waiter scan itself or reaching for raw SQL against `durable_step_checkpoints`. A `Record` (not a
+     * `Map`) because `ProxyRunGateway` serialises the reply over the transport as plain JSON. Entries are
+     * present ONLY for runs currently waiting — an unknown id, a non-suspended id, and a suspended id
+     * parked on something non-event (a bare `ctx.sleep`, an in-flight step) are simply absent, same as a
+     * `listRuns` row with no `waiting`.
+     */
+    waitingFor(runIds: string[]): Promise<Record<string, RunWaiting>>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2820,6 +3012,12 @@ interface RunGateway {
     }): Promise<RunResult | null>;
     retry(runId: string): Promise<RunResult | null>;
     continue(runId: string): Promise<RunResult | null>;
+    /** Re-dispatch every remote step of a run stuck `pending` — the operator recovery for a LOST step
+     *  dispatch (crashed worker / dropped job) that no automatic path re-drives. Returns the run's status
+     *  plus how many steps were re-dispatched, or null if the run is unknown. */
+    redispatchPending(runId: string): Promise<(RunResult & {
+        redispatched: number;
+    }) | null>;
     retryWithInput(runId: string, input: unknown): Promise<{
         runId: string;
     } | null>;
@@ -2832,6 +3030,11 @@ interface RunGateway {
  * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
  * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
  * the wait in a row without fetching that run's timeline.
+ *
+ * `ctx.breakpoint` reuses the signal-waiter machinery (`engine.continue` resumes it via `signal()`
+ * like any other), so without this case it would fall through to the generic `signal` branch with the
+ * raw `bp:<runId>:<seq>` token as its display name — a real bug. Named `'breakpoint'` here instead;
+ * the token carries no separate label to recover cheaply (see {@link RunWaiting.name}).
  */
 declare function classifyWaiterToken(token: string): RunWaiting;
 /**
@@ -3079,6 +3282,35 @@ declare function attributeColumnFor(filter: AttributeFilter): 'numValue' | 'strV
 /** The literal a side-table predicate compares against (booleans → `"true"`/`"false"` strings). */
 declare function attributeOperand(filter: AttributeFilter): string | number;
 
+/**
+ * Read a run's `searchAttributes` through a {@link SearchAttributesSchema}, typed to the schema's
+ * inferred output. **Safe-parse semantics, deliberately lenient** — unlike
+ * `ctx.upsertSearchAttributes` (which is strict: an invalid merge throws), a failed validation here
+ * returns `{}` rather than throwing. This is intentional: `run.searchAttributes` may predate the
+ * schema (an older deploy wrote it under a looser or absent schema, or a run started before this
+ * workflow ever declared one), and a dashboard/read path crashing on old history is worse than it
+ * quietly reporting no typed attributes for that run. Write-time enforcement is what keeps NEW writes
+ * conformant; this is the read-side counterpart for consuming them.
+ *
+ * The schema's `validate` must be synchronous (matching the write-side constraint in
+ * `ctx.upsertSearchAttributes`) — one returning a `Promise` throws with a clear error rather than
+ * being silently awaited or silently treated as a failure.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+ *
+ * const orderAttrs = z.object({ tier: z.enum(['free', 'pro']), amount: z.number() });
+ *
+ * const run = await store.getRun(runId);
+ * const attrs = readSearchAttributes(orderAttrs, run ?? {}); // { tier: 'pro', amount: 42 } | {}
+ * ```
+ */
+declare function readSearchAttributes<S extends SearchAttributesSchema>(schema: S, run: {
+    searchAttributes?: SearchAttributes | undefined;
+}): InferSearchAttributes<S>;
+
 /**
  * Compute the worker group a tenant's run dispatches to. Mirrors the transport's
  * default-is-bare rule (see {@link TransportPool.useNamespace}'s `'default'` no-op): a
@@ -3226,4 +3458,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.js

@@ -1100,6 +1100,11 @@ function normalizeChildOptions(options) {
   } : options ?? {};
 }
 __name(normalizeChildOptions, "normalizeChildOptions");
+function formatIssuePath(path) {
+  if (!path || path.length === 0) return "(root)";
+  return path.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
+}
+__name(formatIssuePath, "formatIssuePath");
 function resolveStepPolicy(config, opts) {
   const policy = {};
   const retries = opts?.retries ?? config?.retries;
@@ -1130,7 +1135,7 @@ var Position = class Position2 {
     this.seq -= 1;
   }
 };
-function createWorkflowCtx(host, runId, compensations, workflow = "") {
+function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttributesSchema) {
   const { store, replay } = host;
   const pos = new Position();
   const readCheckpoint = /* @__PURE__ */ __name((seq) => {
@@ -1599,6 +1604,24 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
       }
       return;
     }
+    if (searchAttributesSchema) {
+      const run = await store.getRun(runId);
+      const merged = {
+        ...run?.searchAttributes ?? {},
+        ...attrs
+      };
+      const result = searchAttributesSchema["~standard"].validate(merged);
+      if (result instanceof Promise) {
+        throw new Error(`workflow "${workflow}": ctx.upsertSearchAttributes schema validation must be synchronous (the searchAttributes schema's \`~standard.validate\` returned a Promise) \u2014 replay-determinism requires a sync validator; drop any async refinement from the schema passed to @Workflow({ searchAttributes }).`);
+      }
+      if (result.issues) {
+        const offendingKeys = [
+          ...new Set(result.issues.map((issue) => formatIssuePath(issue.path)))
+        ];
+        const details = result.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`).join("; ");
+        throw new Error(`workflow "${workflow}": ctx.upsertSearchAttributes rejected by its searchAttributes schema \u2014 offending key(s) ${offendingKeys.join(", ")} \u2014 ${details}`);
+      }
+    }
     await host.upsertSearchAttributes(runId, attrs);
     await writeCheckpoint(instantCheckpoint({
       runId,
@@ -1729,6 +1752,8 @@ var WorkflowEngine = class {
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
   reconcileMs;
+  remoteRedispatchMs;
+  remoteRedispatchMax;
   webhookUrl;
   traceparent;
   context;
@@ -1800,6 +1825,8 @@ var WorkflowEngine = class {
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
     this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
+    this.remoteRedispatchMs = deps.remoteRedispatchMs || void 0;
+    this.remoteRedispatchMax = Math.max(1, deps.remoteRedispatchMax ?? 10);
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -1950,6 +1977,7 @@ var WorkflowEngine = class {
       singleton: opts?.singleton,
       executionTimeoutMs: opts?.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts?.validateInput,
+      searchAttributesSchema: opts?.searchAttributesSchema,
       onEvent: opts?.onEvent,
       eventBatch: opts?.eventBatch,
       // A real, retained in-process body — so `workflowBody` can hand it to an in-app worker, and so
@@ -2511,6 +2539,49 @@ var WorkflowEngine = class {
     };
   }
   /**
+  * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
+  * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
+  * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
+  * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
+  * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+  * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
+  * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
+  * run's current status (with the count re-dispatched), or null if the run is unknown.
+  */
+  async redispatchPending(runId) {
+    const run = await this.store.getRun(runId);
+    if (!run) return null;
+    const pending = (await this.store.listCheckpoints(runId)).filter((cp) => cp.kind === "remote" && cp.status === "pending");
+    let redispatched = 0;
+    for (const cp of pending) {
+      if (!cp.stepId) continue;
+      const reAttempt = cp.attempts + 1;
+      const reEnqueuedAt = /* @__PURE__ */ new Date();
+      await this.store.saveCheckpoint({
+        ...cp,
+        attempts: reAttempt,
+        enqueuedAt: reEnqueuedAt,
+        startedAt: reEnqueuedAt,
+        finishedAt: reEnqueuedAt
+      });
+      await this.dispatchRemoteTask({
+        runId,
+        seq: cp.seq,
+        name: cp.name,
+        stepId: cp.stepId,
+        group: cp.workerGroup ?? sanitizeQueueToken(cp.name),
+        input: cp.input,
+        attempt: reAttempt
+      });
+      redispatched += 1;
+    }
+    return {
+      runId,
+      status: run.status,
+      redispatched
+    };
+  }
+  /**
   * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
   * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
   * the original stays inspectable. Returns the new run's id, or null if `runId` is unknown.
@@ -3606,7 +3677,7 @@ var WorkflowEngine = class {
     const snapshot = await this.store.listCheckpoints(run.id);
     const replay = /* @__PURE__ */ new Map();
     for (const cp of snapshot) replay.set(cp.seq, cp);
-    const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow);
+    const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow, registered?.searchAttributesSchema);
     try {
       const output = await runInWorkflowCtx(ctx, () => fn(ctx, run.input));
       if (this.cancelRequested.has(run.id)) {
@@ -3998,7 +4069,47 @@ var WorkflowEngine = class {
     if (existing?.status === "completed") return existing.output;
     if (this.pool.size === 0) throw new Error("remote steps require a Transport");
     if (step.timeoutMs) return this.callRemoteInMemory(runId, seq, step, input, transport);
-    if (existing?.status === "pending") throw new WorkflowSuspended();
+    if (existing?.status === "pending") {
+      if (this.remoteRedispatchMs == null) throw new WorkflowSuspended();
+      if (existing.wakeAt == null) {
+        const wakeAt = this.clock() + this.remoteRedispatchMs;
+        await this.store.saveCheckpoint({
+          ...existing,
+          wakeAt
+        });
+        throw new WorkflowSuspended(wakeAt);
+      }
+      if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
+      if (existing.attempts >= this.remoteRedispatchMax) {
+        throw new RemoteStepError({
+          message: `remote step "${step.name}" lost \u2014 no result after ${existing.attempts} re-dispatch(es)`,
+          code: "remote_step_lost"
+        });
+      }
+      const reAttempt = existing.attempts + 1;
+      const nextDeadline = this.clock() + this.remoteRedispatchMs;
+      const reEnqueuedAt = /* @__PURE__ */ new Date();
+      await this.store.saveCheckpoint({
+        ...existing,
+        attempts: reAttempt,
+        wakeAt: nextDeadline,
+        enqueuedAt: reEnqueuedAt,
+        startedAt: reEnqueuedAt,
+        finishedAt: reEnqueuedAt
+      });
+      await this.dispatchRemoteTask({
+        runId,
+        seq,
+        name: step.name,
+        stepId: existing.stepId ?? stepId(runId, seq),
+        group: existing.workerGroup ?? tenantGroup(sanitizeQueueToken(step.name), step.partition),
+        input: existing.input,
+        priority: admission?.priority,
+        attempt: reAttempt,
+        transport
+      });
+      throw new WorkflowSuspended(nextDeadline);
+    }
     let attempt = 1;
     if (existing?.status === "failed") {
       const maxAttempts = Math.max(1, step.retries ?? 1);
@@ -4046,18 +4157,17 @@ var WorkflowEngine = class {
       startedAt: enqueuedAt,
       finishedAt: enqueuedAt
     });
-    await this.pool.dispatch({
+    await this.dispatchRemoteTask({
       runId,
       seq,
       name: step.name,
       stepId: id,
       group: tenantGroup(sanitizeQueueToken(step.name), step.partition),
       input,
-      traceparent: this.traceparent?.(),
-      context: this.context?.(),
       priority: admission?.priority,
-      attempt
-    }, transport);
+      attempt,
+      transport
+    });
     this.emit({
       type: "step.started",
       runId,
@@ -4067,6 +4177,23 @@ var WorkflowEngine = class {
     });
     throw new WorkflowSuspended();
   }
+  /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
+  *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
+  *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
+  dispatchRemoteTask(task) {
+    return this.pool.dispatch({
+      runId: task.runId,
+      seq: task.seq,
+      name: task.name,
+      stepId: task.stepId,
+      group: task.group,
+      input: task.input,
+      traceparent: this.traceparent?.(),
+      context: this.context?.(),
+      priority: task.priority,
+      attempt: task.attempt
+    }, task.transport);
+  }
   /**
   * Complete a durable remote step from its worker result and resume the run — runs on whichever
   * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
@@ -4306,12 +4433,17 @@ var TERMINAL_RUN_STATUSES = [
 // src/run-waiting.ts
 var WEBHOOK_PREFIX = "wh:";
 var CHILD_PREFIX = "child:";
+var BREAKPOINT_PREFIX = "bp:";
 var EVENT_PREFIX = "event:";
 function classifyWaiterToken(token) {
   if (token.startsWith(WEBHOOK_PREFIX)) return {
     on: "webhook",
     name: token
   };
+  if (token.startsWith(BREAKPOINT_PREFIX)) return {
+    on: "breakpoint",
+    name: "breakpoint"
+  };
   if (token.startsWith(CHILD_PREFIX)) return {
     on: "child",
     name: token.slice(CHILD_PREFIX.length)
@@ -4732,6 +4864,19 @@ function attributeOperand(filter) {
 }
 __name(attributeOperand, "attributeOperand");
 
+// src/search-attributes-schema.ts
+function readSearchAttributes(schema, run) {
+  const result = schema["~standard"].validate(run.searchAttributes ?? {});
+  if (result instanceof Promise) {
+    throw new Error("readSearchAttributes: schema validation must be synchronous (the searchAttributes schema's `~standard.validate` returned a Promise) \u2014 async Standard Schema validators are not supported.");
+  }
+  if (result.issues) {
+    return {};
+  }
+  return result.value;
+}
+__name(readSearchAttributes, "readSearchAttributes");
+
 // src/tokens.ts
 var STATE_STORE = Symbol.for("nestjs-durable:STATE_STORE");
 var TRANSPORT = Symbol.for("nestjs-durable:TRANSPORT");
@@ -5107,6 +5252,7 @@ export {
   normalizeAttributeRows,
   parseDuration,
   prevCronFireMs,
+  readSearchAttributes,
   resolveRunWaiting,
   runInWorkflowCtx,
   runSchedules,