@dudousxd/nestjs-durable-core 0.63.0 → 0.64.0

package/dist/index.d.cts

@@ -3177,8 +3177,22 @@ declare class WorkflowEngine {
      * cancel flag stays too, re-derived from the status on any later re-drive regardless.
      */
     private compensateAndCancel;
-    /** The run body, lease held + renewed by {@link execute}. */
+    /**
+     * The run body, lease held + renewed by {@link execute}, wrapped in the registered
+     * {@link runDurableExecution} wrappers so an observability scope covers ONE WHOLE TURN.
+     *
+     * The wrap goes here — around the entire turn — rather than tightly around the `fn(ctx, input)`
+     * call, because the store writes that bracket the body (the `pending` → `running` transition, the
+     * step checkpoints, the terminal `settleRun` update) are exactly the queries an operator wants
+     * correlated to the turn that issued them. Narrowing the wrap to the body would leave them
+     * uncorrelated for the sake of a purity that buys nothing.
+     *
+     * Only the TS path is wrapped. {@link runRemoteExecution} does not execute a body at all — it
+     * dispatches a workflow task and awaits the worker's decision — so a scope opened there would
+     * describe a dispatch, not an execution, and would mislead anyone reading the trace.
+     */
     private runExecution;
+    private runExecutionTurn;
     /**
      * Undo every registered saga compensation in strict reverse order — the shared unwind both the
      * run-failure path (`runExecution`'s catch) and the compensating-cancel path
@@ -3670,6 +3684,70 @@ type RoutingResolution = RoutableResolution | BlockedResolution;
  */
 declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
 
+/**
+ * Wrappers around the **real execution** of a unit of durable work — a workflow turn, or a step
+ * handler body. Distinct from {@link StepInterceptor} (`engine.use`), which only sees the in-process
+ * `localStep` primitives (`ctx.now`, `ctx.sideEffect`, `ctx.task`'s dispatch step, saga
+ * compensations): a user's `ctx.step` is ALWAYS dispatched, so its handler runs inside a transport
+ * callback or a worker process where no engine is in scope at all.
+ *
+ * That is exactly why this registry is process-level rather than per-engine. `runStepHandler` is a
+ * free function every transport shares, and a thin worker (`DurableModule` with a `connection` and
+ * no `store`) holds no `WorkflowEngine` to hang a hook off. A per-engine registry could not reach
+ * either, so the seam that covers every deployment shape has to sit above the engine.
+ *
+ * The intended consumer is an observability bridge (Telescope, OTel, a logger) that needs to
+ * establish an ambient scope — an AsyncLocalStorage batch, a span — that the executing code records
+ * into. It is deliberately NOT a transform point: see {@link runDurableExecution}.
+ */
+/** The unit of durable work a wrapper is being invoked around. */
+interface DurableExecution {
+    /** `'workflow'` = one turn of a run's body; `'step'` = one step handler body. */
+    readonly unit: 'workflow' | 'step';
+    readonly runId: string;
+    /** The workflow name. Present on a turn; a dispatched step task does not carry it on the wire. */
+    readonly workflow: string | undefined;
+    /** The step name, for `unit: 'step'`. Undefined for a turn. */
+    readonly name: string | undefined;
+    /** The step's logical position within the run, for `unit: 'step'`. */
+    readonly seq: number | undefined;
+    /** 1-based dispatch attempt, when the task carries one. */
+    readonly attempt: number | undefined;
+}
+/**
+ * Wraps one unit of durable work. Call `next()` to run the body (or the next wrapper). Whatever the
+ * wrapper returns or throws is discarded — see {@link runDurableExecution} for why.
+ */
+type DurableExecutionWrapper = (execution: DurableExecution, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Register a {@link DurableExecutionWrapper}. Returns an unregister function.
+ *
+ * Registering is the ONLY cost an unused hook imposes: with an empty registry
+ * {@link runDurableExecution} returns the body's own promise without allocating a chain, so a host
+ * that wires no observability pays nothing at all on the execution path.
+ */
+declare function useDurableExecution(wrapper: DurableExecutionWrapper): () => void;
+/** Drop every registered wrapper. For tests that must not leak a wrapper into the next file. */
+declare function clearDurableExecutionWrappers(): void;
+/** Whether any wrapper is registered — lets a hot path skip building an execution descriptor. */
+declare function hasDurableExecutionWrappers(): boolean;
+/**
+ * Run `body` inside every registered wrapper and settle with **the body's own outcome**.
+ *
+ * The wrappers' return values and throws are deliberately ignored. An observer that misbehaves —
+ * returns early without calling `next()` is the one case we cannot paper over, but one that throws
+ * *after* the body settled, or swallows the body's error and returns normally, is common enough in
+ * telemetry code — must not be able to change what the workflow saw. A wrapper that turned a failed
+ * step into a completed one would corrupt the run's history and its checkpoints, which is a far
+ * worse failure than a missing trace. This is the same reasoning the bullmq/schedule Telescope
+ * watchers apply when they re-throw the host's error rather than swallowing it, pushed down into
+ * the seam so every wrapper gets it for free instead of having to remember.
+ *
+ * The one unrecoverable case is a wrapper that never calls `next()`: the body did not run, so there
+ * is no outcome to return and we throw rather than invent one.
+ */
+declare function runDurableExecution<T>(execution: DurableExecution, body: () => Promise<T>): Promise<T>;
+
 /** Canonical step id — the stable identity of a step within a run, used for dedupe and
  *  correlation. The format is part of the cross-language wire contract (Python builds the same). */
 declare function stepId(runId: string, seq: number): string;
@@ -4345,4 +4423,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 BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DispatchDiagnostics, type DispatchPlan, type DurableTopology, type DurableWebhook, DurableWorkflow, 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 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 PayloadCodec, type QueueConfig, QueueController, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, 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 WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, canRoute, capableWorkers, classifyWaiterToken, collectMetrics, controlPlaneDescriptor, createStepLogger, currentStep, currentWorkflowCtx, debug, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, parseDuration, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, 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 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 PayloadCodec, type QueueConfig, QueueController, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, 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 WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, controlPlaneDescriptor, createStepLogger, currentStep, currentWorkflowCtx, debug, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, parseDuration, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };

package/dist/index.d.ts

@@ -3177,8 +3177,22 @@ declare class WorkflowEngine {
      * cancel flag stays too, re-derived from the status on any later re-drive regardless.
      */
     private compensateAndCancel;
-    /** The run body, lease held + renewed by {@link execute}. */
+    /**
+     * The run body, lease held + renewed by {@link execute}, wrapped in the registered
+     * {@link runDurableExecution} wrappers so an observability scope covers ONE WHOLE TURN.
+     *
+     * The wrap goes here — around the entire turn — rather than tightly around the `fn(ctx, input)`
+     * call, because the store writes that bracket the body (the `pending` → `running` transition, the
+     * step checkpoints, the terminal `settleRun` update) are exactly the queries an operator wants
+     * correlated to the turn that issued them. Narrowing the wrap to the body would leave them
+     * uncorrelated for the sake of a purity that buys nothing.
+     *
+     * Only the TS path is wrapped. {@link runRemoteExecution} does not execute a body at all — it
+     * dispatches a workflow task and awaits the worker's decision — so a scope opened there would
+     * describe a dispatch, not an execution, and would mislead anyone reading the trace.
+     */
     private runExecution;
+    private runExecutionTurn;
     /**
      * Undo every registered saga compensation in strict reverse order — the shared unwind both the
      * run-failure path (`runExecution`'s catch) and the compensating-cancel path
@@ -3670,6 +3684,70 @@ type RoutingResolution = RoutableResolution | BlockedResolution;
  */
 declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
 
+/**
+ * Wrappers around the **real execution** of a unit of durable work — a workflow turn, or a step
+ * handler body. Distinct from {@link StepInterceptor} (`engine.use`), which only sees the in-process
+ * `localStep` primitives (`ctx.now`, `ctx.sideEffect`, `ctx.task`'s dispatch step, saga
+ * compensations): a user's `ctx.step` is ALWAYS dispatched, so its handler runs inside a transport
+ * callback or a worker process where no engine is in scope at all.
+ *
+ * That is exactly why this registry is process-level rather than per-engine. `runStepHandler` is a
+ * free function every transport shares, and a thin worker (`DurableModule` with a `connection` and
+ * no `store`) holds no `WorkflowEngine` to hang a hook off. A per-engine registry could not reach
+ * either, so the seam that covers every deployment shape has to sit above the engine.
+ *
+ * The intended consumer is an observability bridge (Telescope, OTel, a logger) that needs to
+ * establish an ambient scope — an AsyncLocalStorage batch, a span — that the executing code records
+ * into. It is deliberately NOT a transform point: see {@link runDurableExecution}.
+ */
+/** The unit of durable work a wrapper is being invoked around. */
+interface DurableExecution {
+    /** `'workflow'` = one turn of a run's body; `'step'` = one step handler body. */
+    readonly unit: 'workflow' | 'step';
+    readonly runId: string;
+    /** The workflow name. Present on a turn; a dispatched step task does not carry it on the wire. */
+    readonly workflow: string | undefined;
+    /** The step name, for `unit: 'step'`. Undefined for a turn. */
+    readonly name: string | undefined;
+    /** The step's logical position within the run, for `unit: 'step'`. */
+    readonly seq: number | undefined;
+    /** 1-based dispatch attempt, when the task carries one. */
+    readonly attempt: number | undefined;
+}
+/**
+ * Wraps one unit of durable work. Call `next()` to run the body (or the next wrapper). Whatever the
+ * wrapper returns or throws is discarded — see {@link runDurableExecution} for why.
+ */
+type DurableExecutionWrapper = (execution: DurableExecution, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Register a {@link DurableExecutionWrapper}. Returns an unregister function.
+ *
+ * Registering is the ONLY cost an unused hook imposes: with an empty registry
+ * {@link runDurableExecution} returns the body's own promise without allocating a chain, so a host
+ * that wires no observability pays nothing at all on the execution path.
+ */
+declare function useDurableExecution(wrapper: DurableExecutionWrapper): () => void;
+/** Drop every registered wrapper. For tests that must not leak a wrapper into the next file. */
+declare function clearDurableExecutionWrappers(): void;
+/** Whether any wrapper is registered — lets a hot path skip building an execution descriptor. */
+declare function hasDurableExecutionWrappers(): boolean;
+/**
+ * Run `body` inside every registered wrapper and settle with **the body's own outcome**.
+ *
+ * The wrappers' return values and throws are deliberately ignored. An observer that misbehaves —
+ * returns early without calling `next()` is the one case we cannot paper over, but one that throws
+ * *after* the body settled, or swallows the body's error and returns normally, is common enough in
+ * telemetry code — must not be able to change what the workflow saw. A wrapper that turned a failed
+ * step into a completed one would corrupt the run's history and its checkpoints, which is a far
+ * worse failure than a missing trace. This is the same reasoning the bullmq/schedule Telescope
+ * watchers apply when they re-throw the host's error rather than swallowing it, pushed down into
+ * the seam so every wrapper gets it for free instead of having to remember.
+ *
+ * The one unrecoverable case is a wrapper that never calls `next()`: the body did not run, so there
+ * is no outcome to return and we throw rather than invent one.
+ */
+declare function runDurableExecution<T>(execution: DurableExecution, body: () => Promise<T>): Promise<T>;
+
 /** Canonical step id — the stable identity of a step within a run, used for dedupe and
  *  correlation. The format is part of the cross-language wire contract (Python builds the same). */
 declare function stepId(runId: string, seq: number): string;
@@ -4345,4 +4423,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 BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DispatchDiagnostics, type DispatchPlan, type DurableTopology, type DurableWebhook, DurableWorkflow, 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 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 PayloadCodec, type QueueConfig, QueueController, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, 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 WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, canRoute, capableWorkers, classifyWaiterToken, collectMetrics, controlPlaneDescriptor, createStepLogger, currentStep, currentWorkflowCtx, debug, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, parseDuration, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, 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 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 PayloadCodec, type QueueConfig, QueueController, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, 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 WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, controlPlaneDescriptor, createStepLogger, currentStep, currentWorkflowCtx, debug, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, parseDuration, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };

package/dist/index.js

@@ -481,6 +481,57 @@ function backoffDelay(attempt, options) {
 }
 __name(backoffDelay, "backoffDelay");
 
+// src/execution-hooks.ts
+var wrappers = [];
+function useDurableExecution(wrapper) {
+  wrappers.push(wrapper);
+  return () => {
+    const i = wrappers.indexOf(wrapper);
+    if (i >= 0) wrappers.splice(i, 1);
+  };
+}
+__name(useDurableExecution, "useDurableExecution");
+function clearDurableExecutionWrappers() {
+  wrappers.length = 0;
+}
+__name(clearDurableExecutionWrappers, "clearDurableExecutionWrappers");
+function hasDurableExecutionWrappers() {
+  return wrappers.length > 0;
+}
+__name(hasDurableExecutionWrappers, "hasDurableExecutionWrappers");
+async function runDurableExecution(execution, body) {
+  if (wrappers.length === 0) return body();
+  let outcome;
+  const inner = /* @__PURE__ */ __name(async () => {
+    try {
+      const value = await body();
+      outcome = {
+        ok: true,
+        value
+      };
+      return value;
+    } catch (error2) {
+      outcome = {
+        ok: false,
+        error: error2
+      };
+      throw error2;
+    }
+  }, "inner");
+  const chain = wrappers.reduceRight((next, wrapper) => () => wrapper(execution, next), inner);
+  try {
+    await chain();
+  } catch (error2) {
+    if (outcome === void 0) throw error2;
+  }
+  if (outcome === void 0) {
+    throw new Error("a durable execution wrapper returned without calling next() \u2014 the unit of work never ran");
+  }
+  if (outcome.ok) return outcome.value;
+  throw outcome.error;
+}
+__name(runDurableExecution, "runDurableExecution");
+
 // src/step-logger.ts
 function withDuration(start, now, data) {
   if (data && typeof data === "object" && "durationMs" in data) {
@@ -622,7 +673,14 @@ async function runStepHandler(task, handler) {
   } : result, "withEvents");
   try {
     const logger = createStepLogger(events, Date.now);
-    const output = await 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
+    }, async () => runInStepLogger(logger, () => handler(task.input, logger)));
     return withEvents({
       ...base,
       status: "completed",
@@ -4524,8 +4582,31 @@ var WorkflowEngine = class {
       error: error2
     };
   }
-  /** The run body, lease held + renewed by {@link execute}. */
-  async runExecution(run, fn, registered) {
+  /**
+  * The run body, lease held + renewed by {@link execute}, wrapped in the registered
+  * {@link runDurableExecution} wrappers so an observability scope covers ONE WHOLE TURN.
+  *
+  * The wrap goes here — around the entire turn — rather than tightly around the `fn(ctx, input)`
+  * call, because the store writes that bracket the body (the `pending` → `running` transition, the
+  * step checkpoints, the terminal `settleRun` update) are exactly the queries an operator wants
+  * correlated to the turn that issued them. Narrowing the wrap to the body would leave them
+  * uncorrelated for the sake of a purity that buys nothing.
+  *
+  * Only the TS path is wrapped. {@link runRemoteExecution} does not execute a body at all — it
+  * dispatches a workflow task and awaits the worker's decision — so a scope opened there would
+  * describe a dispatch, not an execution, and would mislead anyone reading the trace.
+  */
+  runExecution(run, fn, registered) {
+    return runDurableExecution({
+      unit: "workflow",
+      runId: run.id,
+      workflow: run.workflow,
+      name: void 0,
+      seq: void 0,
+      attempt: void 0
+    }, () => this.runExecutionTurn(run, fn, registered));
+  }
+  async runExecutionTurn(run, fn, registered) {
     if (run.status === "cancelling") this.cancelRequested.add(run.id);
     if (run.status === "pending") {
       await this.store.updateRun(run.id, {
@@ -6284,6 +6365,7 @@ export {
   canRoute,
   capableWorkers,
   classifyWaiterToken,
+  clearDurableExecutionWrappers,
   collectMetrics,
   controlPlaneDescriptor,
   createStepLogger,
@@ -6297,6 +6379,7 @@ export {
   eventNameOf,
   eventPrefix,
   eventToken,
+  hasDurableExecutionWrappers,
   heartbeatStatus,
   indexWaitersByRun,
   info,
@@ -6316,6 +6399,7 @@ export {
   requiredCapabilities,
   resolveRouting,
   resolveRunWaiting,
+  runDurableExecution,
   runInStepLogger,
   runInWorkflowCtx,
   runSchedules,
@@ -6330,6 +6414,7 @@ export {
   subEvent,
   subProcess,
   tenantGroup,
+  useDurableExecution,
   warn,
   workflowName
 };