@dudousxd/nestjs-durable-telescope 0.7.3 → 0.8.0

package/dist/index.d.cts

@@ -1,28 +1,185 @@
 import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
 import { Watcher, WatcherContext, DataProvider, DashboardSpec } from '@dudousxd/nestjs-telescope';
+import { DurableExecutionWrapper } from '@dudousxd/nestjs-durable-core';
+import { Context } from '@opentelemetry/api';
 
 /**
  * A Telescope watcher that turns durable-workflow lifecycle events into Telescope entries, so
  * runs and steps (including remote/Python steps) show up alongside the app's requests, queries
  * and jobs in the Telescope UI — under the **Workflows** tab.
  *
- * It also **trace-groups** a run: a root span is opened per run and every entry is recorded inside
- * that span's OTel context (step entries inside a child `step …` span). Telescope's trace-context
- * provider stamps each entry with the active span, so a whole workflow shows up as a single trace
- * on the Traces page — run → steps — with each entry carrying the run's `traceId`. When the host has
- * no OTel SDK the spans are no-ops and entries simply carry no trace (the prior behaviour).
+ * It does two things, and the second is the one that makes a failing workflow debuggable:
+ *
+ * 1. **Records an entry per engine event**, stamped with the run's trace (see
+ *    {@link runTraceContext}), so a whole run — across all its turns, all its steps and every
+ *    process that executed them — reads as a single trace at `/telescope#/traces/<id>`.
+ *
+ * 2. **Opens a Telescope batch around the execution itself** (see {@link durableExecutionScope}),
+ *    through the engine's `useDurableExecution` seam. Without this, everything a workflow turn or a
+ *    step handler *did* — its queries, its logs, the exception it threw — was recorded outside any
+ *    batch and outside any span: traceless, and so impossible to correlate back to the step that
+ *    caused it. Recording an event after the fact cannot fix that; the scope has to be open while
+ *    the body runs.
  *
  * Add it to `TelescopeModule.forRoot({ watchers: [new DurableTelescopeWatcher()] })`. It resolves
  * the engine from the (global) durable providers and subscribes to its events.
+ *
+ * ## What is NOT covered
+ *
+ * A **remote step** — one whose handler lives in another runtime, e.g. the Python worker — executes
+ * out of process, so nothing here can wrap it. Its lifecycle still shows up (the engine emits
+ * `step.started`/`step.completed`/`step.failed` when it dispatches and when the result lands, and
+ * those entries carry the run's trace id), but the queries and exceptions *inside* that handler are
+ * that runtime's to record. Because the trace id is derived from the run id rather than held in this
+ * process, a remote runtime that derives it the same way joins the same trace — but that is a change
+ * on its side, not something this watcher can do on its behalf.
+ *
+ * A **remote workflow** (a run whose body itself lives in another runtime) is likewise unwrapped:
+ * the engine dispatches a workflow task and awaits a decision rather than executing a body, and a
+ * scope around a dispatch would describe the wrong thing.
  */
 declare class DurableTelescopeWatcher implements Watcher {
     readonly type = "durable";
-    /** Open root span per run, so step entries nest under it and share its traceId. */
-    private readonly roots;
+    /** Removes the execution wrapper from the engine's process-level registry. */
+    private disposeScope;
     register(ctx: WatcherContext): void;
+    /**
+     * Detach the execution wrapper. The `Watcher` SPI has no teardown hook, so nothing calls this in a
+     * running app — where the wrapper should live exactly as long as the process does. It exists so a
+     * test that registers a watcher does not leave a wrapper behind in the process-level registry for
+     * the next test to trip over.
+     */
+    unregister(): void;
     private tags;
 }
 
+/** What the scope publishes to anything recording on this async path. */
+interface DurableScope {
+    /** The run whose unit of work is executing. */
+    readonly runId: string;
+    /** The run's trace — see {@link runTraceId}. */
+    readonly traceId: string;
+    /** This scope's span within that trace. Stable for every entry recorded inside it. */
+    readonly spanId: string;
+    /**
+     * Identity of the wrapper that opened this scope. Reuse is only ever offered to the wrapper that
+     * owns the scope: two Telescope instances in one process (a torn-down test module whose wrapper
+     * outlived it, an app that mounts two consoles) would otherwise have the first one's scope
+     * silently suppress the second one's batch, and the second console would record everything
+     * batchless while looking correctly wired.
+     */
+    readonly owner: object;
+}
+/** The durable execution scope active on this async path, or undefined outside one. */
+declare function currentDurableScope(): DurableScope | undefined;
+/**
+ * Builds the {@link DurableExecutionWrapper} that puts every workflow turn and every step handler
+ * body inside a Telescope batch and an OTel span, so the queries, logs and exceptions those bodies
+ * produce are correlated to the unit of durable work that caused them instead of landing traceless.
+ *
+ * ## Why a batch around execution and not around the event
+ *
+ * The watcher's engine-event subscription records what *happened*, after the fact. A batch opened
+ * there would contain exactly one entry — the durable entry itself — and nothing the step actually
+ * did, because by then the handler has returned and the exception it threw has long since been
+ * recorded with no batch at all. Wrapping the execution is the only shape that puts the failing code
+ * inside the scope.
+ *
+ * ## Nesting: reuse the batch when the same run already has one open on this path
+ *
+ * With an in-process transport (event-emitter, in-memory, the DB transport's inline path) a
+ * dispatched step's handler starts synchronously inside the turn that dispatched it, and the result
+ * it produces resumes the next turn on that same async path — so the whole run is one unbroken
+ * causal chain. Opening a fresh batch at each hop would split that chain across many batch ids for
+ * no gain: Telescope's entry model has no parent-batch pointer, so the split is not recoverable in
+ * the UI — the step's queries would appear in a batch with nothing visible causing them.
+ *
+ * So the rule is the causal one, not the syntactic one: a unit reuses the batch when THIS wrapper
+ * already has one open for THIS run on this async path. The consequence is worth stating plainly,
+ * because it differs by transport and looks like an inconsistency if you meet it unprepared:
+ *
+ *  - **in-process transport** — one batch for the whole run (every turn, every step), because it is
+ *    genuinely one chain;
+ *  - **queue-backed transport** (BullMQ, SQS, a thin worker) — one batch per turn and one per step,
+ *    because each really is a separate entry point, in a separate process, with no ambient scope to
+ *    inherit.
+ *
+ * What holds either way is the trace: every entry of a run carries {@link runTraceId}, so the run is
+ * one trace whether it executed in one process or twenty. That invariant is the thing to rely on;
+ * batch granularity follows the execution shape.
+ *
+ * A different run is a different chain and always gets its own batch. That includes a child
+ * workflow: it has its own run id, its own timeline and its own dashboard row, and its trace is
+ * anchored on ITS run id (see {@link runTraceContext}), so it reads as a related-but-distinct trace
+ * instead of being folded into the parent's. The parent/child relationship is already carried by the
+ * run graph; flattening the batches to restate it would erase the child's own boundaries and gain
+ * nothing.
+ *
+ * ## Origin
+ *
+ * `BatchOrigin` in `@dudousxd/nestjs-telescope` is the closed union
+ * `'http' | 'queue' | 'schedule' | 'cli' | 'manual'` — it has no durable/workflow member. Widening
+ * it belongs to that repo and a coordinated release, so this uses `'queue'`, which is also the
+ * honest description: durable work reaches an executor by being dispatched over a transport
+ * (BullMQ, SQS, an event emitter), exactly like the jobs the BullMQ watcher marks `'queue'`.
+ */
+declare function durableExecutionScope(ctx: WatcherContext): DurableExecutionWrapper;
+/** Minimal structural view of Telescope's `TraceContextProvider` (it is one method, and typing
+ *  against the interface would drag a value import in for nothing). */
+interface TraceContextLike {
+    current(): {
+        traceId: string;
+        spanId: string;
+    } | null;
+}
+/**
+ * A Telescope `traceContext` provider that reports the active durable scope, so entries recorded by
+ * OTHER watchers (queries, cache, outbound HTTP) during a workflow turn or a step body carry the
+ * run's trace id.
+ *
+ * Wire it as `TelescopeModule.forRoot({ traceContext: durableTraceContext() })`.
+ *
+ * This exists because Telescope resolves an entry's trace id from an ambient OTel span, and
+ * `@opentelemetry/api` on its own propagates nothing: without a registered context manager
+ * `context.with(...)` is a no-op and `getActiveSpan()` is always undefined. An app that runs a full
+ * OTel SDK needs none of this — it should pass `OtelTraceContextProvider` (optionally as the
+ * `delegate` below, which is then consulted first so the app's real spans win), and the scope's
+ * spans hang off the run's trace anyway. An app that runs no OTel at all — the common case — would
+ * otherwise get correlated batches and no trace ids, which is half the feature.
+ */
+declare function durableTraceContext(delegate?: TraceContextLike): TraceContextLike;
+
+/**
+ * The trace a run's spans hang under, DERIVED FROM THE RUN ID rather than held as a live root span.
+ *
+ * The obvious implementation — open a root span on `run.started`, keep it in a map, end it when the
+ * run settles — cannot work for a durable workflow. A run suspends: `ctx.step` dispatches and the
+ * turn unwinds, and the step body then executes minutes (or days) later, on a different turn, very
+ * often in a different process. A live root span would either have to be ended at every suspension —
+ * fragmenting one run into a trace per turn, so the step that failed is in a different trace from
+ * the turn that dispatched it — or held open across the suspension, which pins a span object for the
+ * lifetime of a workflow that is explicitly designed to wait for days.
+ *
+ * Hashing the run id sidesteps both. The trace id is a pure function of the run, so every turn and
+ * every step of a run lands in ONE trace with no state held anywhere, and a worker in another
+ * process computes the same id from the same run id — which is what makes a remotely-executed step
+ * correlate with the run that dispatched it at all.
+ *
+ * The parent span context is marked `isRemote` because that is what it is: a reference to a trace
+ * whose "root" is the run itself, not a span this process ever recorded.
+ */
+declare function runTraceId(runId: string): string;
+/**
+ * An OTel {@link Context} whose active span context is the run's synthetic root. Spans started
+ * against it are children of the run, and Telescope's trace-context provider stamps every entry
+ * recorded inside it with {@link runTraceId}.
+ *
+ * `TraceFlags.SAMPLED` is set deliberately: a non-sampled parent leaves the derived span
+ * non-recording, and its span context would then never reach an exporter — the run would be
+ * traceable in Telescope but invisible in any OTel backend, which is the confusing half-state.
+ */
+declare function runTraceContext(runId: string, parent?: Context): Context;
+
 /** The first-class Telescope extension for nestjs-durable: watcher + Workflows dashboard. */
 declare function durableTelescopeExtension(opts?: {
     runHref?: string;
@@ -103,4 +260,4 @@ declare function durableDashboard(opts?: {
     recentFailuresWindowMs?: number;
 }): DashboardSpec;
 
-export { DurableTelescopeWatcher, durableDashboard, durableDurationProvider, durableRecentFailuresProvider, durableRunsOverTimeProvider, durableStateBreakdownProvider, durableStateProvider, durableSuccessRateProvider, durableTelescopeExtension, durableThroughputProvider, durableTimeseriesProvider, durableWorkerHealthProvider, durableWorkerStatusProvider };
+export { type DurableScope, DurableTelescopeWatcher, currentDurableScope, durableDashboard, durableDurationProvider, durableExecutionScope, durableRecentFailuresProvider, durableRunsOverTimeProvider, durableStateBreakdownProvider, durableStateProvider, durableSuccessRateProvider, durableTelescopeExtension, durableThroughputProvider, durableTimeseriesProvider, durableTraceContext, durableWorkerHealthProvider, durableWorkerStatusProvider, runTraceContext, runTraceId };

package/dist/index.d.ts

@@ -1,28 +1,185 @@
 import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
 import { Watcher, WatcherContext, DataProvider, DashboardSpec } from '@dudousxd/nestjs-telescope';
+import { DurableExecutionWrapper } from '@dudousxd/nestjs-durable-core';
+import { Context } from '@opentelemetry/api';
 
 /**
  * A Telescope watcher that turns durable-workflow lifecycle events into Telescope entries, so
  * runs and steps (including remote/Python steps) show up alongside the app's requests, queries
  * and jobs in the Telescope UI — under the **Workflows** tab.
  *
- * It also **trace-groups** a run: a root span is opened per run and every entry is recorded inside
- * that span's OTel context (step entries inside a child `step …` span). Telescope's trace-context
- * provider stamps each entry with the active span, so a whole workflow shows up as a single trace
- * on the Traces page — run → steps — with each entry carrying the run's `traceId`. When the host has
- * no OTel SDK the spans are no-ops and entries simply carry no trace (the prior behaviour).
+ * It does two things, and the second is the one that makes a failing workflow debuggable:
+ *
+ * 1. **Records an entry per engine event**, stamped with the run's trace (see
+ *    {@link runTraceContext}), so a whole run — across all its turns, all its steps and every
+ *    process that executed them — reads as a single trace at `/telescope#/traces/<id>`.
+ *
+ * 2. **Opens a Telescope batch around the execution itself** (see {@link durableExecutionScope}),
+ *    through the engine's `useDurableExecution` seam. Without this, everything a workflow turn or a
+ *    step handler *did* — its queries, its logs, the exception it threw — was recorded outside any
+ *    batch and outside any span: traceless, and so impossible to correlate back to the step that
+ *    caused it. Recording an event after the fact cannot fix that; the scope has to be open while
+ *    the body runs.
  *
  * Add it to `TelescopeModule.forRoot({ watchers: [new DurableTelescopeWatcher()] })`. It resolves
  * the engine from the (global) durable providers and subscribes to its events.
+ *
+ * ## What is NOT covered
+ *
+ * A **remote step** — one whose handler lives in another runtime, e.g. the Python worker — executes
+ * out of process, so nothing here can wrap it. Its lifecycle still shows up (the engine emits
+ * `step.started`/`step.completed`/`step.failed` when it dispatches and when the result lands, and
+ * those entries carry the run's trace id), but the queries and exceptions *inside* that handler are
+ * that runtime's to record. Because the trace id is derived from the run id rather than held in this
+ * process, a remote runtime that derives it the same way joins the same trace — but that is a change
+ * on its side, not something this watcher can do on its behalf.
+ *
+ * A **remote workflow** (a run whose body itself lives in another runtime) is likewise unwrapped:
+ * the engine dispatches a workflow task and awaits a decision rather than executing a body, and a
+ * scope around a dispatch would describe the wrong thing.
  */
 declare class DurableTelescopeWatcher implements Watcher {
     readonly type = "durable";
-    /** Open root span per run, so step entries nest under it and share its traceId. */
-    private readonly roots;
+    /** Removes the execution wrapper from the engine's process-level registry. */
+    private disposeScope;
     register(ctx: WatcherContext): void;
+    /**
+     * Detach the execution wrapper. The `Watcher` SPI has no teardown hook, so nothing calls this in a
+     * running app — where the wrapper should live exactly as long as the process does. It exists so a
+     * test that registers a watcher does not leave a wrapper behind in the process-level registry for
+     * the next test to trip over.
+     */
+    unregister(): void;
     private tags;
 }
 
+/** What the scope publishes to anything recording on this async path. */
+interface DurableScope {
+    /** The run whose unit of work is executing. */
+    readonly runId: string;
+    /** The run's trace — see {@link runTraceId}. */
+    readonly traceId: string;
+    /** This scope's span within that trace. Stable for every entry recorded inside it. */
+    readonly spanId: string;
+    /**
+     * Identity of the wrapper that opened this scope. Reuse is only ever offered to the wrapper that
+     * owns the scope: two Telescope instances in one process (a torn-down test module whose wrapper
+     * outlived it, an app that mounts two consoles) would otherwise have the first one's scope
+     * silently suppress the second one's batch, and the second console would record everything
+     * batchless while looking correctly wired.
+     */
+    readonly owner: object;
+}
+/** The durable execution scope active on this async path, or undefined outside one. */
+declare function currentDurableScope(): DurableScope | undefined;
+/**
+ * Builds the {@link DurableExecutionWrapper} that puts every workflow turn and every step handler
+ * body inside a Telescope batch and an OTel span, so the queries, logs and exceptions those bodies
+ * produce are correlated to the unit of durable work that caused them instead of landing traceless.
+ *
+ * ## Why a batch around execution and not around the event
+ *
+ * The watcher's engine-event subscription records what *happened*, after the fact. A batch opened
+ * there would contain exactly one entry — the durable entry itself — and nothing the step actually
+ * did, because by then the handler has returned and the exception it threw has long since been
+ * recorded with no batch at all. Wrapping the execution is the only shape that puts the failing code
+ * inside the scope.
+ *
+ * ## Nesting: reuse the batch when the same run already has one open on this path
+ *
+ * With an in-process transport (event-emitter, in-memory, the DB transport's inline path) a
+ * dispatched step's handler starts synchronously inside the turn that dispatched it, and the result
+ * it produces resumes the next turn on that same async path — so the whole run is one unbroken
+ * causal chain. Opening a fresh batch at each hop would split that chain across many batch ids for
+ * no gain: Telescope's entry model has no parent-batch pointer, so the split is not recoverable in
+ * the UI — the step's queries would appear in a batch with nothing visible causing them.
+ *
+ * So the rule is the causal one, not the syntactic one: a unit reuses the batch when THIS wrapper
+ * already has one open for THIS run on this async path. The consequence is worth stating plainly,
+ * because it differs by transport and looks like an inconsistency if you meet it unprepared:
+ *
+ *  - **in-process transport** — one batch for the whole run (every turn, every step), because it is
+ *    genuinely one chain;
+ *  - **queue-backed transport** (BullMQ, SQS, a thin worker) — one batch per turn and one per step,
+ *    because each really is a separate entry point, in a separate process, with no ambient scope to
+ *    inherit.
+ *
+ * What holds either way is the trace: every entry of a run carries {@link runTraceId}, so the run is
+ * one trace whether it executed in one process or twenty. That invariant is the thing to rely on;
+ * batch granularity follows the execution shape.
+ *
+ * A different run is a different chain and always gets its own batch. That includes a child
+ * workflow: it has its own run id, its own timeline and its own dashboard row, and its trace is
+ * anchored on ITS run id (see {@link runTraceContext}), so it reads as a related-but-distinct trace
+ * instead of being folded into the parent's. The parent/child relationship is already carried by the
+ * run graph; flattening the batches to restate it would erase the child's own boundaries and gain
+ * nothing.
+ *
+ * ## Origin
+ *
+ * `BatchOrigin` in `@dudousxd/nestjs-telescope` is the closed union
+ * `'http' | 'queue' | 'schedule' | 'cli' | 'manual'` — it has no durable/workflow member. Widening
+ * it belongs to that repo and a coordinated release, so this uses `'queue'`, which is also the
+ * honest description: durable work reaches an executor by being dispatched over a transport
+ * (BullMQ, SQS, an event emitter), exactly like the jobs the BullMQ watcher marks `'queue'`.
+ */
+declare function durableExecutionScope(ctx: WatcherContext): DurableExecutionWrapper;
+/** Minimal structural view of Telescope's `TraceContextProvider` (it is one method, and typing
+ *  against the interface would drag a value import in for nothing). */
+interface TraceContextLike {
+    current(): {
+        traceId: string;
+        spanId: string;
+    } | null;
+}
+/**
+ * A Telescope `traceContext` provider that reports the active durable scope, so entries recorded by
+ * OTHER watchers (queries, cache, outbound HTTP) during a workflow turn or a step body carry the
+ * run's trace id.
+ *
+ * Wire it as `TelescopeModule.forRoot({ traceContext: durableTraceContext() })`.
+ *
+ * This exists because Telescope resolves an entry's trace id from an ambient OTel span, and
+ * `@opentelemetry/api` on its own propagates nothing: without a registered context manager
+ * `context.with(...)` is a no-op and `getActiveSpan()` is always undefined. An app that runs a full
+ * OTel SDK needs none of this — it should pass `OtelTraceContextProvider` (optionally as the
+ * `delegate` below, which is then consulted first so the app's real spans win), and the scope's
+ * spans hang off the run's trace anyway. An app that runs no OTel at all — the common case — would
+ * otherwise get correlated batches and no trace ids, which is half the feature.
+ */
+declare function durableTraceContext(delegate?: TraceContextLike): TraceContextLike;
+
+/**
+ * The trace a run's spans hang under, DERIVED FROM THE RUN ID rather than held as a live root span.
+ *
+ * The obvious implementation — open a root span on `run.started`, keep it in a map, end it when the
+ * run settles — cannot work for a durable workflow. A run suspends: `ctx.step` dispatches and the
+ * turn unwinds, and the step body then executes minutes (or days) later, on a different turn, very
+ * often in a different process. A live root span would either have to be ended at every suspension —
+ * fragmenting one run into a trace per turn, so the step that failed is in a different trace from
+ * the turn that dispatched it — or held open across the suspension, which pins a span object for the
+ * lifetime of a workflow that is explicitly designed to wait for days.
+ *
+ * Hashing the run id sidesteps both. The trace id is a pure function of the run, so every turn and
+ * every step of a run lands in ONE trace with no state held anywhere, and a worker in another
+ * process computes the same id from the same run id — which is what makes a remotely-executed step
+ * correlate with the run that dispatched it at all.
+ *
+ * The parent span context is marked `isRemote` because that is what it is: a reference to a trace
+ * whose "root" is the run itself, not a span this process ever recorded.
+ */
+declare function runTraceId(runId: string): string;
+/**
+ * An OTel {@link Context} whose active span context is the run's synthetic root. Spans started
+ * against it are children of the run, and Telescope's trace-context provider stamps every entry
+ * recorded inside it with {@link runTraceId}.
+ *
+ * `TraceFlags.SAMPLED` is set deliberately: a non-sampled parent leaves the derived span
+ * non-recording, and its span context would then never reach an exporter — the run would be
+ * traceable in Telescope but invisible in any OTel backend, which is the confusing half-state.
+ */
+declare function runTraceContext(runId: string, parent?: Context): Context;
+
 /** The first-class Telescope extension for nestjs-durable: watcher + Workflows dashboard. */
 declare function durableTelescopeExtension(opts?: {
     runHref?: string;
@@ -103,4 +260,4 @@ declare function durableDashboard(opts?: {
     recentFailuresWindowMs?: number;
 }): DashboardSpec;
 
-export { DurableTelescopeWatcher, durableDashboard, durableDurationProvider, durableRecentFailuresProvider, durableRunsOverTimeProvider, durableStateBreakdownProvider, durableStateProvider, durableSuccessRateProvider, durableTelescopeExtension, durableThroughputProvider, durableTimeseriesProvider, durableWorkerHealthProvider, durableWorkerStatusProvider };
+export { type DurableScope, DurableTelescopeWatcher, currentDurableScope, durableDashboard, durableDurationProvider, durableExecutionScope, durableRecentFailuresProvider, durableRunsOverTimeProvider, durableStateBreakdownProvider, durableStateProvider, durableSuccessRateProvider, durableTelescopeExtension, durableThroughputProvider, durableTimeseriesProvider, durableTraceContext, durableWorkerHealthProvider, durableWorkerStatusProvider, runTraceContext, runTraceId };

package/dist/index.js

@@ -2,24 +2,137 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/durable-telescope.watcher.ts
-import { WorkflowEngine } from "@dudousxd/nestjs-durable-core";
-import { SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { WorkflowEngine, useDurableExecution } from "@dudousxd/nestjs-durable-core";
+import { SpanStatusCode as SpanStatusCode2, context as context3, trace as trace3 } from "@opentelemetry/api";
+
+// src/durable-execution-scope.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import { SpanStatusCode, context as context2, trace as trace2 } from "@opentelemetry/api";
+
+// src/durable-run-trace.ts
+import { createHash } from "node:crypto";
+import { TraceFlags, context, trace } from "@opentelemetry/api";
+function runTraceId(runId) {
+  return createHash("sha256").update(`durable:run:${runId}`).digest("hex").slice(0, 32);
+}
+__name(runTraceId, "runTraceId");
+function runSpanId(runId) {
+  return createHash("sha256").update(`durable:run-span:${runId}`).digest("hex").slice(0, 16);
+}
+__name(runSpanId, "runSpanId");
+function runTraceContext(runId, parent = context.active()) {
+  return trace.setSpanContext(parent, {
+    traceId: runTraceId(runId),
+    spanId: runSpanId(runId),
+    traceFlags: TraceFlags.SAMPLED,
+    isRemote: true
+  });
+}
+__name(runTraceContext, "runTraceContext");
+
+// src/durable-execution-scope.ts
+var activeScope = new AsyncLocalStorage();
+function currentDurableScope() {
+  return activeScope.getStore();
+}
+__name(currentDurableScope, "currentDurableScope");
+var DURABLE_BATCH_ORIGIN = "queue";
+function spanName(execution) {
+  if (execution.unit === "step") return `step ${execution.name ?? "?"}`;
+  return `workflow ${execution.workflow ?? "?"}`;
+}
+__name(spanName, "spanName");
+function spanAttributes(execution) {
+  const attributes = {
+    "durable.run_id": execution.runId
+  };
+  if (execution.workflow !== void 0) attributes["durable.workflow"] = execution.workflow;
+  if (execution.name !== void 0) attributes["durable.step.name"] = execution.name;
+  if (execution.seq !== void 0) attributes["durable.step.seq"] = execution.seq;
+  if (execution.attempt !== void 0) attributes["durable.step.attempt"] = execution.attempt;
+  return attributes;
+}
+__name(spanAttributes, "spanAttributes");
+function durableExecutionScope(ctx) {
+  const tracer = trace2.getTracer("@dudousxd/nestjs-durable-telescope");
+  const owner = {};
+  return (execution, next) => {
+    const open = activeScope.getStore();
+    if (open?.owner === owner && open.runId === execution.runId) return next();
+    if (ctx.config.enabled === false) return next();
+    try {
+      const parent = runTraceContext(execution.runId);
+      const span = tracer.startSpan(spanName(execution), {
+        attributes: spanAttributes(execution)
+      }, parent);
+      const spanContext = span.spanContext();
+      const scope = {
+        runId: execution.runId,
+        traceId: runTraceId(execution.runId),
+        spanId: span.isRecording() ? spanContext.spanId : randomBytes(8).toString("hex"),
+        owner
+      };
+      return context2.with(trace2.setSpan(parent, span), () => activeScope.run(scope, () => ctx.runInBatch(DURABLE_BATCH_ORIGIN, next).then((value) => {
+        span.end();
+        return value;
+      }, (error) => {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          ...error instanceof Error ? {
+            message: error.message
+          } : {}
+        });
+        span.end();
+        throw error;
+      })));
+    } catch {
+      return next();
+    }
+  };
+}
+__name(durableExecutionScope, "durableExecutionScope");
+function durableTraceContext(delegate) {
+  return {
+    current() {
+      const fromDelegate = delegate?.current() ?? null;
+      if (fromDelegate) return fromDelegate;
+      const scope = activeScope.getStore();
+      return scope ? {
+        traceId: scope.traceId,
+        spanId: scope.spanId
+      } : null;
+    }
+  };
+}
+__name(durableTraceContext, "durableTraceContext");
+
+// src/durable-telescope.watcher.ts
 var DurableTelescopeWatcher = class {
   static {
     __name(this, "DurableTelescopeWatcher");
   }
   type = "durable";
-  /** Open root span per run, so step entries nest under it and share its traceId. */
-  roots = /* @__PURE__ */ new Map();
+  /** Removes the execution wrapper from the engine's process-level registry. */
+  disposeScope;
   register(ctx) {
+    this.disposeScope?.();
+    this.disposeScope = useDurableExecution(durableExecutionScope(ctx));
     const engine = ctx.moduleRef.get(WorkflowEngine, {
       strict: false
     });
     if (typeof engine?.subscribe !== "function") return;
-    const tracer = trace.getTracer("@dudousxd/nestjs-durable-telescope");
+    const tracer = trace3.getTracer("@dudousxd/nestjs-durable-telescope");
     engine.subscribe((event) => {
       const record = /* @__PURE__ */ __name(() => ctx.record({
         type: this.type,
+        // Stated explicitly rather than left to the ambient span, and the Recorder honours an
+        // explicit `traceId` above everything else. A lifecycle event is very often emitted
+        // OUTSIDE any execution scope — a remote step's result lands in a transport callback, a
+        // recovery sweep emits for a run this process never executed — and those entries are
+        // exactly the ones an operator follows into the trace. We know the run, so we know the
+        // trace; there is no reason to let it depend on where the emit happened to land.
+        traceId: runTraceId(event.runId),
         content: {
           event: event.type,
           workflow: event.workflow,
@@ -33,16 +146,7 @@ var DurableTelescopeWatcher = class {
         },
         tags: this.tags(event)
       }), "record");
-      if (event.type === "run.started") {
-        this.roots.set(event.runId, tracer.startSpan(`workflow ${event.workflow ?? "?"}`, {
-          attributes: {
-            "durable.run_id": event.runId,
-            "durable.workflow": event.workflow
-          }
-        }));
-      }
-      const root = this.roots.get(event.runId);
-      const base = root ? trace.setSpan(context.active(), root) : context.active();
+      const base = runTraceContext(event.runId);
       if (event.name != null && event.seq != null) {
         const step = tracer.startSpan(`step ${event.name}`, {
           attributes: {
@@ -51,27 +155,32 @@ var DurableTelescopeWatcher = class {
             "durable.step.kind": event.kind
           }
         }, base);
-        context.with(trace.setSpan(base, step), record);
+        if (event.type === "step.failed") {
+          const message = event.error?.message;
+          step.setStatus(message !== void 0 ? {
+            code: SpanStatusCode2.ERROR,
+            message
+          } : {
+            code: SpanStatusCode2.ERROR
+          });
+        }
+        context3.with(trace3.setSpan(base, step), record);
         step.end();
       } else {
-        context.with(base, record);
-      }
-      if (event.type === "run.completed" || event.type === "run.suspended") {
-        root?.end();
-        this.roots.delete(event.runId);
-      } else if (event.type === "run.failed") {
-        const message = event.error?.message;
-        root?.setStatus(message !== void 0 ? {
-          code: SpanStatusCode.ERROR,
-          message
-        } : {
-          code: SpanStatusCode.ERROR
-        });
-        root?.end();
-        this.roots.delete(event.runId);
+        context3.with(base, record);
       }
     });
   }
+  /**
+  * Detach the execution wrapper. The `Watcher` SPI has no teardown hook, so nothing calls this in a
+  * running app — where the wrapper should live exactly as long as the process does. It exists so a
+  * test that registers a watcher does not leave a wrapper behind in the process-level registry for
+  * the next test to trip over.
+  */
+  unregister() {
+    this.disposeScope?.();
+    this.disposeScope = void 0;
+  }
   tags(event) {
     const tags = [
       "durable",
@@ -878,8 +987,10 @@ function durableTelescopeExtension(opts = {}) {
 __name(durableTelescopeExtension, "durableTelescopeExtension");
 export {
   DurableTelescopeWatcher,
+  currentDurableScope,
   durableDashboard,
   durableDurationProvider,
+  durableExecutionScope,
   durableRecentFailuresProvider,
   durableRunsOverTimeProvider,
   durableStateBreakdownProvider,
@@ -888,7 +999,10 @@ export {
   durableTelescopeExtension,
   durableThroughputProvider,
   durableTimeseriesProvider,
+  durableTraceContext,
   durableWorkerHealthProvider,
-  durableWorkerStatusProvider
+  durableWorkerStatusProvider,
+  runTraceContext,
+  runTraceId
 };
 //# sourceMappingURL=index.js.map