@dudousxd/nestjs-durable-core 0.72.0 → 0.72.1

package/dist/index.d.cts

@@ -2505,6 +2505,32 @@ declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
  * ambient workflow context (by design — a handler is not the workflow body).
  */
 declare function currentWorkflowCtx(): WorkflowCtx | undefined;
+/**
+ * The ambient STEP scope: which workflow ctx's checkpointed step body (if any) is executing on this
+ * async path. The engine installs it around every in-body step execution (`ctx.localStep`,
+ * `ctx.transaction`, and everything built on them) so the ctx primitives can refuse to run from
+ * inside a step body — see {@link NestedWorkflowCallError}. `owner` is the identity of the ctx whose
+ * step is running, so a DIFFERENT run's body executed inline from a step (e.g. a step that signals a
+ * run which resumes on this async path) is never mistaken for a nested call.
+ *
+ * Shared per process under a `Symbol.for` key, for the same duplicate-copy reason as the ctx storage.
+ */
+interface StepScope {
+    readonly owner: object;
+    readonly step: string;
+}
+/** Run `fn` as the body of step `step` of the ctx identified by `owner`. Engine-internal. */
+declare function runInStepScope<T>(owner: object, step: string, fn: () => T): T;
+/** The step body currently executing on this async path, or `undefined` outside one. */
+declare function currentStepScope(): StepScope | undefined;
+/**
+ * Run `fn` with NO ambient workflow ctx and no step scope — for a dispatched `@Step` handler. A
+ * handler is not the workflow body (on a remote worker it never sees one), but an in-process
+ * transport invokes it on the body's async path, where the parent's ctx would otherwise leak in and
+ * turn a handler's `MyWorkflow.start()` into a journal-corrupting `ctx.startChild` of a parent that
+ * is already suspended. Clearing it makes in-process and remote handlers behave identically.
+ */
+declare function runOutsideWorkflowCtx<T>(fn: () => T): T;
 
 /**
  * Run `fn` with `logger` as the ambient step logger. Engine-internal: wraps every execution of a
@@ -3870,7 +3896,23 @@ declare class WorkflowEngine {
     start<TInput>(workflow: string, input: TInput, runId: string, opts?: StartOptions): Promise<RunResult>;
     /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
     getRun(runId: string): Promise<WorkflowRun | null>;
+    /**
+     * Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
+     * driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
+     * also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
+     * dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
+     * timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
+     * terminal too.
+     */
     resume(runId: string): Promise<RunResult>;
+    /**
+     * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
+     * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
+     * these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
+     * stale waiter or a late result left behind by a failed run silently re-executes its body.
+     */
+    private resumeImplicit;
+    private resumeRun;
     /**
      * The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
      * `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
@@ -4883,6 +4925,26 @@ declare class NonDeterminismError extends Error {
     readonly seq: number;
     constructor(runId: string, seq: number, expected: string, recorded: string);
 }
+/**
+ * Thrown AT THE CALL SITE when a workflow-ctx primitive (`ctx.startChild`, `ctx.child`, `ctx.step`,
+ * `ctx.sleep`, `ctx.sideEffect`, … — or a `MyWorkflow.start()`/`.execute()` static, which route to
+ * them through the ambient ctx) is called from INSIDE the body of a checkpointed step
+ * (`ctx.localStep`, `ctx.transaction`, `ctx.sideEffect`, `ctx.now`, `ctx.task`'s dispatch).
+ *
+ * A step body runs once and is replayed from its checkpoint WITHOUT re-running, so a primitive it
+ * called claims a journal position on the first run that no replay ever claims again: every later
+ * position shifts and the run dies on its next replay with a `NonDeterminismError` far from the
+ * cause. Failing here instead names the real mistake. Move the call out of the step body (into the
+ * workflow body), or — from a dispatched `@Step` handler — start a top-level run.
+ *
+ * A `FatalError` (code `nested_workflow_call`): the step is not retried, the run fails.
+ */
+declare class NestedWorkflowCallError extends FatalError {
+    readonly runId: string;
+    readonly primitive: string;
+    readonly step: string;
+    constructor(runId: string, primitive: string, step: string);
+}
 /**
  * Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
  * (input index, child run id, error message) and presents an aggregate message summarizing the count
@@ -5829,4 +5891,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, 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, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };

package/dist/index.d.ts

@@ -2505,6 +2505,32 @@ declare function runInWorkflowCtx<T>(ctx: WorkflowCtx, fn: () => T): T;
  * ambient workflow context (by design — a handler is not the workflow body).
  */
 declare function currentWorkflowCtx(): WorkflowCtx | undefined;
+/**
+ * The ambient STEP scope: which workflow ctx's checkpointed step body (if any) is executing on this
+ * async path. The engine installs it around every in-body step execution (`ctx.localStep`,
+ * `ctx.transaction`, and everything built on them) so the ctx primitives can refuse to run from
+ * inside a step body — see {@link NestedWorkflowCallError}. `owner` is the identity of the ctx whose
+ * step is running, so a DIFFERENT run's body executed inline from a step (e.g. a step that signals a
+ * run which resumes on this async path) is never mistaken for a nested call.
+ *
+ * Shared per process under a `Symbol.for` key, for the same duplicate-copy reason as the ctx storage.
+ */
+interface StepScope {
+    readonly owner: object;
+    readonly step: string;
+}
+/** Run `fn` as the body of step `step` of the ctx identified by `owner`. Engine-internal. */
+declare function runInStepScope<T>(owner: object, step: string, fn: () => T): T;
+/** The step body currently executing on this async path, or `undefined` outside one. */
+declare function currentStepScope(): StepScope | undefined;
+/**
+ * Run `fn` with NO ambient workflow ctx and no step scope — for a dispatched `@Step` handler. A
+ * handler is not the workflow body (on a remote worker it never sees one), but an in-process
+ * transport invokes it on the body's async path, where the parent's ctx would otherwise leak in and
+ * turn a handler's `MyWorkflow.start()` into a journal-corrupting `ctx.startChild` of a parent that
+ * is already suspended. Clearing it makes in-process and remote handlers behave identically.
+ */
+declare function runOutsideWorkflowCtx<T>(fn: () => T): T;
 
 /**
  * Run `fn` with `logger` as the ambient step logger. Engine-internal: wraps every execution of a
@@ -3870,7 +3896,23 @@ declare class WorkflowEngine {
     start<TInput>(workflow: string, input: TInput, runId: string, opts?: StartOptions): Promise<RunResult>;
     /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
     getRun(runId: string): Promise<WorkflowRun | null>;
+    /**
+     * Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
+     * driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
+     * also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
+     * dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
+     * timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
+     * terminal too.
+     */
     resume(runId: string): Promise<RunResult>;
+    /**
+     * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
+     * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
+     * these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
+     * stale waiter or a late result left behind by a failed run silently re-executes its body.
+     */
+    private resumeImplicit;
+    private resumeRun;
     /**
      * The registration for an UNREGISTERED run, INHERITED from its nearest REMOTE ancestor — or
      * `undefined` if it has none (the skew-protection error case in {@link resume}). Callers check the
@@ -4883,6 +4925,26 @@ declare class NonDeterminismError extends Error {
     readonly seq: number;
     constructor(runId: string, seq: number, expected: string, recorded: string);
 }
+/**
+ * Thrown AT THE CALL SITE when a workflow-ctx primitive (`ctx.startChild`, `ctx.child`, `ctx.step`,
+ * `ctx.sleep`, `ctx.sideEffect`, … — or a `MyWorkflow.start()`/`.execute()` static, which route to
+ * them through the ambient ctx) is called from INSIDE the body of a checkpointed step
+ * (`ctx.localStep`, `ctx.transaction`, `ctx.sideEffect`, `ctx.now`, `ctx.task`'s dispatch).
+ *
+ * A step body runs once and is replayed from its checkpoint WITHOUT re-running, so a primitive it
+ * called claims a journal position on the first run that no replay ever claims again: every later
+ * position shifts and the run dies on its next replay with a `NonDeterminismError` far from the
+ * cause. Failing here instead names the real mistake. Move the call out of the step body (into the
+ * workflow body), or — from a dispatched `@Step` handler — start a top-level run.
+ *
+ * A `FatalError` (code `nested_workflow_call`): the step is not retried, the run fails.
+ */
+declare class NestedWorkflowCallError extends FatalError {
+    readonly runId: string;
+    readonly primitive: string;
+    readonly step: string;
+    constructor(runId: string, primitive: string, step: string);
+}
 /**
  * Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
  * (input index, child run id, error message) and presents an aggregate message summarizing the count
@@ -5829,4 +5891,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, 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, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };

package/dist/index.js

@@ -172,6 +172,27 @@ function currentWorkflowCtx() {
   return storage.getStore();
 }
 __name(currentWorkflowCtx, "currentWorkflowCtx");
+var STEP_SCOPE_KEY = Symbol.for("nestjs-durable:ambient-step-scope");
+var stepScopeRef = globalThis;
+if (!stepScopeRef[STEP_SCOPE_KEY]) {
+  stepScopeRef[STEP_SCOPE_KEY] = new AsyncLocalStorage();
+}
+var stepScopeStorage = stepScopeRef[STEP_SCOPE_KEY];
+function runInStepScope(owner, step, fn) {
+  return stepScopeStorage.run({
+    owner,
+    step
+  }, fn);
+}
+__name(runInStepScope, "runInStepScope");
+function currentStepScope() {
+  return stepScopeStorage.getStore();
+}
+__name(currentStepScope, "currentStepScope");
+function runOutsideWorkflowCtx(fn) {
+  return storage.exit(() => stepScopeStorage.exit(fn));
+}
+__name(runOutsideWorkflowCtx, "runOutsideWorkflowCtx");
 
 // src/ambient-step.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
@@ -334,6 +355,21 @@ var NonDeterminismError = class extends Error {
     this.seq = seq;
   }
 };
+var NestedWorkflowCallError = class extends FatalError {
+  static {
+    __name(this, "NestedWorkflowCallError");
+  }
+  runId;
+  primitive;
+  step;
+  constructor(runId, primitive, step) {
+    super(`ctx.${primitive}() was called inside the body of step "${step}" (run ${runId}). Workflow primitives (child/startChild/step/sleep/signals/sideEffect/\u2026, and MyWorkflow.start()/.execute() via the ambient ctx) must be called from the workflow body, never from inside a step body: the step's checkpoint replays without re-running it, so the nested call would shift every later journal position and corrupt the run on replay. Move the call out of the step.`, "nested_workflow_call");
+    this.name = "NestedWorkflowCallError";
+    this.runId = runId;
+    this.primitive = primitive;
+    this.step = step;
+  }
+};
 var GatherError = class extends Error {
   static {
     __name(this, "GatherError");
@@ -690,14 +726,19 @@ async function runStepHandler(task, handler) {
   } : result, "withEvents");
   try {
     const logger = createStepLogger(events, Date.now);
-    const output = await runDurableExecution({
-      unit: "step",
-      runId: task.runId,
-      workflow: void 0,
-      name: task.name,
-      seq: task.seq,
-      attempt: task.attempt
-    }, async () => runInStepLogger(logger, () => handler(task.input, logger)));
+    const output = await runDurableExecution(
+      {
+        unit: "step",
+        runId: task.runId,
+        workflow: void 0,
+        name: task.name,
+        seq: task.seq,
+        attempt: task.attempt
+      },
+      // Outside any ambient workflow ctx: an in-process transport runs the handler on the parent
+      // body's async path, but a handler is not the body (see `runOutsideWorkflowCtx`).
+      async () => runOutsideWorkflowCtx(() => runInStepLogger(logger, () => handler(task.input, logger)))
+    );
     return withEvents({
       ...base,
       status: "completed",
@@ -2601,10 +2642,15 @@ var Position = class Position2 {
   rewind() {
     this.seq -= 1;
   }
+  /** The position the NEXT primitive would claim, without claiming it. */
+  peek() {
+    return this.seq + 1;
+  }
 };
 function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttributesSchema) {
   const { store, replay } = host;
   const pos = new Position();
+  const scopeOwner = {};
   const readCheckpoint = /* @__PURE__ */ __name((seq) => {
     const hit = replay?.get(seq);
     if (hit !== void 0) return hit;
@@ -2650,7 +2696,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         };
         const body = /* @__PURE__ */ __name(() => {
           const logger = createStepLogger(events, host.clock);
-          return runInStepLogger(logger, () => fn(logger));
+          return runInStepScope(scopeOwner, name, () => runInStepLogger(logger, () => fn(logger)));
         }, "body");
         const output = host.interceptStep ? await host.interceptStep(invocation, body) : await body();
         await host.completeStep({
@@ -2703,7 +2749,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     }
     if (existing && existing.status === "completed") return existing.output;
     return store.transaction(async (tx) => {
-      const output = await fn(tx.raw);
+      const output = await runInStepScope(scopeOwner, name, () => fn(tx.raw));
       const cp = instantCheckpoint({
         runId,
         seq: current,
@@ -3212,30 +3258,49 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     });
   }
   __name(step, "step");
+  const nestedStep = /* @__PURE__ */ __name(() => {
+    const scope = currentStepScope();
+    return scope !== void 0 && scope.owner === scopeOwner ? scope.step : void 0;
+  }, "nestedStep");
+  const guard = /* @__PURE__ */ __name((primitive, fn) => (...args) => {
+    const stepName = nestedStep();
+    if (stepName === void 0) return fn(...args);
+    return (async () => {
+      if (await readCheckpoint(pos.peek())) return fn(...args);
+      throw new NestedWorkflowCallError(runId, primitive, stepName);
+    })();
+  }, "guard");
+  const guardedWebhook = /* @__PURE__ */ __name(() => {
+    const stepName = nestedStep();
+    if (stepName !== void 0 && !replay?.get(pos.peek())) {
+      throw new NestedWorkflowCallError(runId, "webhook", stepName);
+    }
+    return webhook();
+  }, "guardedWebhook");
   return {
     runId,
-    step,
-    localStep,
-    upsertSearchAttributes,
-    transaction,
-    callEntity,
-    signalEntity,
-    sleep,
-    sleepUntil,
+    step: guard("step", step),
+    localStep: guard("localStep", localStep),
+    upsertSearchAttributes: guard("upsertSearchAttributes", upsertSearchAttributes),
+    transaction: guard("transaction", transaction),
+    callEntity: guard("callEntity", callEntity),
+    signalEntity: guard("signalEntity", signalEntity),
+    sleep: guard("sleep", sleep),
+    sleepUntil: guard("sleepUntil", sleepUntil),
     continueAsNew,
-    waitForSignal,
-    waitForEvent,
-    task,
-    child,
-    all,
-    startChild,
-    breakpoint,
-    webhook,
-    setEvent,
-    onUpdate,
-    patched,
-    now,
-    sideEffect
+    waitForSignal: guard("waitForSignal", waitForSignal),
+    waitForEvent: guard("waitForEvent", waitForEvent),
+    task: guard("task", task),
+    child: guard("child", child),
+    all: guard("all", all),
+    startChild: guard("startChild", startChild),
+    breakpoint: guard("breakpoint", breakpoint),
+    webhook: guardedWebhook,
+    setEvent: guard("setEvent", setEvent),
+    onUpdate: guard("onUpdate", onUpdate),
+    patched: guard("patched", patched),
+    now: guard("now", now),
+    sideEffect: guard("sideEffect", sideEffect)
   };
 }
 __name(createWorkflowCtx, "createWorkflowCtx");
@@ -3837,10 +3902,30 @@ var WorkflowEngine = class {
   getRun(runId) {
     return this.store.getRun(runId);
   }
-  async resume(runId) {
+  /**
+  * Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
+  * driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
+  * also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
+  * dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
+  * timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
+  * terminal too.
+  */
+  resume(runId) {
+    return this.resumeRun(runId, true);
+  }
+  /**
+  * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
+  * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
+  * these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
+  * stale waiter or a late result left behind by a failed run silently re-executes its body.
+  */
+  resumeImplicit(runId) {
+    return this.resumeRun(runId, false);
+  }
+  async resumeRun(runId, allowFailed) {
     const run = await this.store.getRun(runId);
     if (!run) throw new Error(`run ${runId} not found`);
-    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead") {
+    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead" || run.status === "failed" && !allowFailed) {
       return {
         runId,
         status: run.status,
@@ -4289,7 +4374,7 @@ var WorkflowEngine = class {
     const nowMs = this.clock();
     const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
     if (!acquired) return null;
-    return this.resume(runId).catch((err) => {
+    return this.resumeImplicit(runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -4510,7 +4595,7 @@ var WorkflowEngine = class {
       if (!acquired) continue;
       try {
         const settled = onLocked ? await onLocked(run) : void 0;
-        results.push(settled ?? await this.resume(run.id));
+        results.push(settled ?? await this.resumeImplicit(run.id));
       } catch (error2) {
         console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, error2);
       }
@@ -4607,7 +4692,7 @@ var WorkflowEngine = class {
       // for an ordinary (non-fan) signal/child await.
       parallelGroup: waiter.parallelGroup
     }));
-    return this.resume(waiter.runId).catch((err) => {
+    return this.resumeImplicit(waiter.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -4723,7 +4808,7 @@ var WorkflowEngine = class {
   async cancel(runId, opts) {
     const run = await this.store.getRun(runId);
     if (!run) return null;
-    if (run.status === "completed" || run.status === "cancelled" || run.status === "dead") {
+    if (TERMINAL_RUN_STATUSES.includes(run.status)) {
       return {
         runId,
         status: run.status,
@@ -4752,7 +4837,7 @@ var WorkflowEngine = class {
         }).catch(() => void 0);
       }
       queueMicrotask(() => {
-        void this.resume(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
+        void this.resumeImplicit(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
       });
       await this.cancelChildren(runId, opts);
       return {
@@ -5587,7 +5672,7 @@ var WorkflowEngine = class {
       const checkpoint = await this.store.getCheckpoint(runId, cmd.seq);
       if (checkpoint && checkpoint.status !== "pending") {
         setTimeout(() => {
-          void this.resume(runId).catch(() => void 0);
+          void this.resumeImplicit(runId).catch(() => void 0);
         }, 0).unref?.();
         return;
       }
@@ -5929,7 +6014,7 @@ var WorkflowEngine = class {
             kind: "signal",
             output: payload
           }));
-          setTimeout(() => void this.resume(run.id).catch(() => void 0), 0);
+          setTimeout(() => void this.resumeImplicit(run.id).catch(() => void 0), 0);
         }, "deliverBuffered");
         const buffered = await this.store.takeBufferedSignal(cmd.signal);
         if (buffered) {
@@ -6743,7 +6828,7 @@ var WorkflowEngine = class {
       queueMs: startedAt.getTime() - cp.enqueuedAt.getTime(),
       durationMs: finishedAt.getTime() - startedAt.getTime()
     });
-    await this.resume(result.runId).catch((err) => {
+    await this.resumeImplicit(result.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -6844,7 +6929,7 @@ var WorkflowEngine = class {
       ...waiters
     ];
     waiters.clear();
-    for (const runId of runIds) void this.resume(runId).catch(() => void 0);
+    for (const runId of runIds) void this.resumeImplicit(runId).catch(() => void 0);
   }
   /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
   async releaseQueueSlot(id) {
@@ -7996,6 +8081,7 @@ export {
   InMemoryTransport,
   LEGACY_V1_CAPABILITIES,
   LEGACY_V1_PROTOCOL,
+  NestedWorkflowCallError,
   NonDeterminismError,
   QueueController,
   RUN_VALUE_FACET_LIMIT,
@@ -8042,6 +8128,7 @@ export {
   coveredTokens,
   createStepLogger,
   currentStep,
+  currentStepScope,
   currentWorkflowCtx,
   debug,
   describeWorker,
@@ -8083,7 +8170,9 @@ export {
   resolveRunWaiting,
   runDurableExecution,
   runInStepLogger,
+  runInStepScope,
   runInWorkflowCtx,
+  runOutsideWorkflowCtx,
   runSchedules,
   runStepHandler,
   runValueFacetsFromRuns,