@dudousxd/nestjs-durable-core 0.62.1 → 0.64.0

package/dist/index.d.cts

@@ -627,6 +627,24 @@ interface WorkflowRun {
      * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
      */
     namespace?: string | undefined;
+    /**
+     * The npm package that DECLARED this run's workflow — e.g. `@dudousxd/nestjs-catalog-pipeline` for
+     * a workflow shipped by a library, or the host app's own `package.json` `name` for one written in
+     * the app. This is a CODE-PROVENANCE axis ("which lib owns this body"), NOT a tenancy axis — for
+     * that, see {@link namespace}.
+     *
+     * Stamped at creation from the workflow's registration, exactly as {@link namespace} is stamped
+     * from the creating engine. It is DERIVED, never caller input: `StartOptions` has no `origin`, so
+     * nothing a caller passes to `start` can make a run claim another lib's name.
+     *
+     * `undefined` means UNKNOWN — never "the app". It is what you get for a run created before this
+     * field existed, for a registration path that carries no origin (`registerRemote`, convention
+     * routing, a synthesized remote child, or a bare `engine.register` with no `origin` option), and
+     * for a workflow whose declaring package could not be resolved with confidence. A wrong origin is
+     * worse than an absent one: a filter that silently drops runs looks exactly like runs that never
+     * existed, so callers must render unknown as unknown and never fold it into a real package.
+     */
+    origin?: string | undefined;
     /**
      * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
      * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
@@ -1045,6 +1063,15 @@ interface RunQuery {
     attributes?: AttributeFilter[] | undefined;
     /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
     namespace?: string | undefined;
+    /**
+     * Restrict to runs whose workflow was declared by this package (exact match against
+     * {@link WorkflowRun.origin}), ANDed with the other predicates.
+     *
+     * A run with NO origin (unknown — see the field) matches no `origin` value at all, so a UI facet
+     * built on this must keep an "all origins" option: filtering by any single package silently hides
+     * every unattributed run, which reads to an operator as "those runs do not exist".
+     */
+    origin?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -2262,7 +2289,14 @@ declare class EventAccumulators {
 }
 
 type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
-/** Options for {@link WorkflowEngine.start}. */
+/**
+ * Options for {@link WorkflowEngine.start}.
+ *
+ * Note the absence of `origin`: {@link WorkflowRun.origin} says which PACKAGE declared the workflow,
+ * which is a property of the registered code, not of whoever started it. It is taken from the
+ * registration and nothing here can override it — otherwise one caller could label its runs as
+ * another lib's, and an origin filter would quietly lie.
+ */
 interface StartOptions {
     /** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
     tags?: string[] | undefined;
@@ -2596,6 +2630,12 @@ declare class WorkflowEngine {
         /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5).
          *  Only meaningful with `group`/`executor` (a remote/group-served workflow). Absent = runs anywhere. */
         requires?: string[] | undefined;
+        /** The package that DECLARED this workflow, stamped onto every run started from it (see
+         *  {@link WorkflowRun.origin}). Supplied by the registering integration — `@dudousxd/nestjs-durable`
+         *  derives it from the `@Workflow` class's declaring file — never by whoever calls `start`. Omit
+         *  when it cannot be derived with confidence: absent means UNKNOWN, and an absent origin is far
+         *  cheaper to live with than a wrong one. */
+        origin?: string | undefined;
     }): void;
     /**
      * The retained in-process body for `name@version`, for an IN-APP worker that consumes this engine's
@@ -3137,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
@@ -3630,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;
@@ -4305,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

@@ -627,6 +627,24 @@ interface WorkflowRun {
      * store persists it as `'default'`. Read paths (dashboard, `getRun`) are NOT namespace-scoped.
      */
     namespace?: string | undefined;
+    /**
+     * The npm package that DECLARED this run's workflow — e.g. `@dudousxd/nestjs-catalog-pipeline` for
+     * a workflow shipped by a library, or the host app's own `package.json` `name` for one written in
+     * the app. This is a CODE-PROVENANCE axis ("which lib owns this body"), NOT a tenancy axis — for
+     * that, see {@link namespace}.
+     *
+     * Stamped at creation from the workflow's registration, exactly as {@link namespace} is stamped
+     * from the creating engine. It is DERIVED, never caller input: `StartOptions` has no `origin`, so
+     * nothing a caller passes to `start` can make a run claim another lib's name.
+     *
+     * `undefined` means UNKNOWN — never "the app". It is what you get for a run created before this
+     * field existed, for a registration path that carries no origin (`registerRemote`, convention
+     * routing, a synthesized remote child, or a bare `engine.register` with no `origin` option), and
+     * for a workflow whose declaring package could not be resolved with confidence. A wrong origin is
+     * worse than an absent one: a filter that silently drops runs looks exactly like runs that never
+     * existed, so callers must render unknown as unknown and never fold it into a real package.
+     */
+    origin?: string | undefined;
     /**
      * Dispatch priority for a REMOTE run (one advanced by a {@link WorkflowExecutor} over a broker):
      * carried onto each {@link WorkflowTask} so an urgent child workflow can jump ahead of enqueued
@@ -1045,6 +1063,15 @@ interface RunQuery {
     attributes?: AttributeFilter[] | undefined;
     /** Restrict to runs in this namespace (exact match), ANDed with the other predicates. */
     namespace?: string | undefined;
+    /**
+     * Restrict to runs whose workflow was declared by this package (exact match against
+     * {@link WorkflowRun.origin}), ANDed with the other predicates.
+     *
+     * A run with NO origin (unknown — see the field) matches no `origin` value at all, so a UI facet
+     * built on this must keep an "all origins" option: filtering by any single package silently hides
+     * every unattributed run, which reads to an operator as "those runs do not exist".
+     */
+    origin?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
 }
@@ -2262,7 +2289,14 @@ declare class EventAccumulators {
 }
 
 type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
-/** Options for {@link WorkflowEngine.start}. */
+/**
+ * Options for {@link WorkflowEngine.start}.
+ *
+ * Note the absence of `origin`: {@link WorkflowRun.origin} says which PACKAGE declared the workflow,
+ * which is a property of the registered code, not of whoever started it. It is taken from the
+ * registration and nothing here can override it — otherwise one caller could label its runs as
+ * another lib's, and an origin filter would quietly lie.
+ */
 interface StartOptions {
     /** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
     tags?: string[] | undefined;
@@ -2596,6 +2630,12 @@ declare class WorkflowEngine {
         /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5).
          *  Only meaningful with `group`/`executor` (a remote/group-served workflow). Absent = runs anywhere. */
         requires?: string[] | undefined;
+        /** The package that DECLARED this workflow, stamped onto every run started from it (see
+         *  {@link WorkflowRun.origin}). Supplied by the registering integration — `@dudousxd/nestjs-durable`
+         *  derives it from the `@Workflow` class's declaring file — never by whoever calls `start`. Omit
+         *  when it cannot be derived with confidence: absent means UNKNOWN, and an absent origin is far
+         *  cheaper to live with than a wrong one. */
+        origin?: string | undefined;
     }): void;
     /**
      * The retained in-process body for `name@version`, for an IN-APP worker that consumes this engine's
@@ -3137,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
@@ -3630,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;
@@ -4305,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",
@@ -2558,6 +2616,7 @@ var WorkflowEngine = class {
       onEvent: opts?.onEvent,
       eventBatch: opts?.eventBatch,
       requires: opts?.requires,
+      origin: opts?.origin,
       // A real, retained in-process body — so `workflowBody` can hand it to an in-app worker, and so
       // it is NOT confused with the throwing stub `registerRemote` installs for a body-less remote.
       hasBody: true
@@ -2784,6 +2843,11 @@ var WorkflowEngine = class {
       workflowVersion: registered.version,
       status: "pending",
       namespace: opts?.namespace ?? this.namespace,
+      // DERIVED from the registration, exactly like `namespace` is derived from this engine — there is
+      // deliberately no `opts.origin`, so a caller cannot label its run as another package's work.
+      // `undefined` when the registration carried none (remote/convention/synthesized child, or a
+      // registrar that could not resolve the declaring package): unknown, not "the app".
+      origin: registered.origin,
       input,
       tags,
       searchAttributes: opts?.searchAttributes,
@@ -4518,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, {
@@ -6129,6 +6216,7 @@ var InMemoryStateStore = class {
     if (query.statuses) runs = runs.filter((r) => query.statuses?.includes(r.status));
     if (query.tag) runs = runs.filter((r) => r.tags?.includes(query.tag));
     if (query.namespace !== void 0) runs = runs.filter((r) => r.namespace === query.namespace);
+    if (query.origin !== void 0) runs = runs.filter((r) => r.origin === query.origin);
     if (query.attributes?.length) {
       let candidates = null;
       for (const f of query.attributes) {
@@ -6277,6 +6365,7 @@ export {
   canRoute,
   capableWorkers,
   classifyWaiterToken,
+  clearDurableExecutionWrappers,
   collectMetrics,
   controlPlaneDescriptor,
   createStepLogger,
@@ -6290,6 +6379,7 @@ export {
   eventNameOf,
   eventPrefix,
   eventToken,
+  hasDurableExecutionWrappers,
   heartbeatStatus,
   indexWaitersByRun,
   info,
@@ -6309,6 +6399,7 @@ export {
   requiredCapabilities,
   resolveRouting,
   resolveRunWaiting,
+  runDurableExecution,
   runInStepLogger,
   runInWorkflowCtx,
   runSchedules,
@@ -6323,6 +6414,7 @@ export {
   subEvent,
   subProcess,
   tenantGroup,
+  useDurableExecution,
   warn,
   workflowName
 };