@heystack/otel 0.15.0 → 0.16.0

package/dist/workers.js

@@ -16,8 +16,9 @@ import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { buildExporterConfig, DEFAULT_ENDPOINT, releaseResourceAttributes, } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 import { llmRequestAttrs, llmResponseAttrs, llmContentAttrs, llmOperationName, resolveLLMProvider, scanSseStreamForUsage, } from "./llm-enrich.js";
-import { instrumentEnv } from "./workers-bindings.js";
+import { instrumentEnv, makeProxy, runWithSpan } from "./workers-bindings.js";
 import { makeSampler, loadRemoteSamplingRate } from "./workers-sampler.js";
+import { makeTraceparent } from "./traceparent.js";
 // `ExportResult` / `ExportResultCode` mirror `@opentelemetry/core`. We define
 // them inline (structurally identical) rather than import them: core is only a
 // transitive dep of sdk-trace-base and isn't reliably resolvable, and keeping it
@@ -412,7 +413,7 @@ function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch
                 }
                 return;
             }
-            const adapter = new NativeSpanAdapter(nativeSpan, true);
+            const adapter = new NativeSpanAdapter(nativeSpan);
             const { attrs, parsedReqBody } = llmRequestSide(resolved, url, init);
             adapter.setAttributes({ ...attrs, "server.address": url.hostname });
             try {
@@ -511,7 +512,7 @@ function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
             },
         }, active);
         const sc = span.spanContext();
-        const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+        const traceparent = makeTraceparent(sc);
         const [reqInput, reqInit] = injectTraceparent(input, init, traceparent);
         // gen_ai enrichment — request side (direct host or configured gateway).
         const url = parseTarget(input);
@@ -571,6 +572,85 @@ export function __resetFetchInstrumentation() {
 // ---------------------------------------------------------------------------
 // Exporter
 // ---------------------------------------------------------------------------
+/**
+ * Bounded in-export resilience: ONE automatic retry for network errors /
+ * 429 / 5xx. The backoff starts at {@link RETRY_BASE_DELAY_MS} with jitter and
+ * the total added wait across retries never exceeds {@link RETRY_TOTAL_CAP_MS}
+ * (~2s) so an ingest blip can't pin a request handler; a `Retry-After` header
+ * (seconds form) on 429 refines the delay within that same cap.
+ */
+const EXPORT_MAX_ATTEMPTS = 2;
+const RETRY_BASE_DELAY_MS = 250;
+const RETRY_TOTAL_CAP_MS = 2_000;
+/** Upper bound on concurrently-tracked in-flight exports (`pending` set). */
+const MAX_PENDING_EXPORTS = 512;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Parse the seconds form of `Retry-After`; HTTP-date form returns undefined. */
+function parseRetryAfterSeconds(header) {
+    if (!header)
+        return undefined;
+    const s = Number.parseInt(header.trim(), 10);
+    return Number.isFinite(s) && s > 0 ? s : undefined;
+}
+/**
+ * Backoff for the single retry: honour `Retry-After` when present (429),
+ * otherwise base delay + jitter; always clamped into the remaining total cap.
+ */
+function nextRetryDelayMs(remainingBudgetMs, retryAfterSeconds) {
+    const hinted = retryAfterSeconds !== undefined && retryAfterSeconds > 0
+        ? retryAfterSeconds * 1000
+        : RETRY_BASE_DELAY_MS + Math.random() * RETRY_BASE_DELAY_MS;
+    return Math.max(0, Math.min(hinted, remainingBudgetMs));
+}
+/**
+ * One-per-isolate advisory when exports complete with NEITHER a `waitUntil`
+ * handoff NOR an OpenNext context borrow available — i.e. delivery fell back
+ * to the pending set, where traces are lost unless someone drains explicitly.
+ */
+let warnedNoHandoff = false;
+let manualFlushObserved = false;
+let requestDrainWired = false;
+function warnIfNoHandoffOnce() {
+    if (manualFlushObserved || requestDrainWired || warnedNoHandoff)
+        return;
+    warnedNoHandoff = true;
+    console.warn("[heystack] trace exports have no waitUntil handoff (no ExecutionContext wiring detected). " +
+        "Wrap your Worker's ctx with wrapExecutionContext(ctx), or use instrument(), so exports are " +
+        "drained before isolate teardown; otherwise traces rely on flushHeystack() and may be lost.");
+}
+/** Record an explicit flushHeystack() so the no-handoff advisory stays quiet. */
+function markManualFlushObserved() {
+    manualFlushObserved = true;
+}
+/**
+ * Drain BOTH the provider's span processor AND the exporter's in-flight POSTs.
+ * Awaiting only provider.forceFlush() would return before the export POST
+ * completes, letting the isolate be torn down and silently dropping the trace.
+ */
+async function drainProvider(provider) {
+    await provider.forceFlush().catch(() => { });
+    await provider.heystackExporter.forceFlush().catch(() => { });
+}
+/**
+ * The drain raced against an ~8s timeout so a hung forceFlush (e.g. an ingest
+ * that never responds) can't pin the isolate until the platform CPU timeout
+ * kills it (#25). On timeout we stop waiting; the POST is still in-flight and
+ * may yet complete, we just don't block the isolate on it indefinitely.
+ */
+function drainWithTimeout(provider) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(resolve, DRAIN_TIMEOUT_MS);
+    });
+    return Promise.race([drainProvider(provider), timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+/** Upper bound on one drain race — shared by instrument() and wrapExecutionContext. */
+const DRAIN_TIMEOUT_MS = 8_000;
 /**
  * A WinterCG-compatible OTLP/JSON span exporter. POSTs ended spans to the
  * Heystack ingest using the platform `fetch` — no Node built-ins.
@@ -581,6 +661,8 @@ export class HeystackSpanExporter {
     ingestHost;
     headers;
     shutdownState = false;
+    /** Exports rejected before network work because the in-flight cap was hit. */
+    droppedPending = 0;
     /**
      * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
      * completes promise here and removes it on `finally`. `forceFlush()` awaits
@@ -629,47 +711,45 @@ export class HeystackSpanExporter {
             return;
         }
         const body = JSON.stringify(serializeSpans(exportable));
-        // Build the fetch chain as a promise we retain, so forceFlush() can await
-        // the actual network write. It resolves (never rejects) once the POST has
-        // completed (success or fail) and resultCallback has been invoked.
+        // Build the export chain as a promise we retain, so forceFlush() can await
+        // the actual network write — INCLUDING the bounded retry/backoff, so a
+        // waitUntil drain keeps the isolate alive until retries settle too. It
+        // resolves (never rejects) once the POST attempts are done (success or
+        // final failure) and resultCallback has been invoked.
         //
-        // The POST runs inside a tracing-suppressed context so that host fetch
-        // auto-instrumentation (e.g. Next/OpenNext) does NOT create a CLIENT span
-        // for it — which would otherwise be exported and re-captured, a sustained
-        // feedback loop. As a belt-and-suspenders second layer it also uses the
-        // CAPTURED platform fetch (when our outbound-fetch wrapper is installed), so
-        // the export can never be re-entered by that wrapper regardless of context.
-        const doFetch = _originalFetch ?? fetch;
-        const p = context
-            .with(suppressTracing(context.active()), () => doFetch(this.url, { method: "POST", headers: this.headers, body }))
-            .then((res) => {
-            if (res.ok) {
-                resultCallback({ code: ExportResultCode.SUCCESS });
-            }
-            else {
-                resultCallback({
-                    code: ExportResultCode.FAILED,
-                    error: new Error(`Heystack ingest responded ${res.status} ${res.statusText}`),
-                });
-            }
-        })
-            .catch((error) => {
+        // Each POST attempt runs inside a tracing-suppressed context so that host
+        // fetch auto-instrumentation (e.g. Next/OpenNext) does NOT create a CLIENT
+        // span for it — which would otherwise be exported and re-captured, a
+        // sustained feedback loop. As a belt-and-suspenders second layer it also
+        // uses the CAPTURED platform fetch (when our outbound-fetch wrapper is
+        // installed), so the export can never be re-entered by that wrapper.
+        const reservation = this.reservePending();
+        if (!reservation) {
+            this.droppedPending++;
             resultCallback({
                 code: ExportResultCode.FAILED,
-                error: error instanceof Error ? error : new Error(String(error)),
+                error: new Error(`Heystack export dropped: ${MAX_PENDING_EXPORTS} exports are already in flight`),
             });
-        });
-        this.pending.add(p);
-        p.finally(() => this.pending.delete(p));
+            return;
+        }
+        const doFetch = _originalFetch ?? fetch;
+        const post = this.postWithRetry(doFetch, body, resultCallback);
+        // postWithRetry should not reject; handle both branches so a future change
+        // cannot leak the reserved slot or create an unhandled rejection.
+        void post.then(reservation.release, reservation.release);
+        const p = reservation.pending;
         // Keep the isolate alive until the POST completes. Priority:
         //   1. an explicit `waitUntil` override (set via initHeystackWorkers).
         //   2. the OpenNext Cloudflare request context's `ctx.waitUntil` — the
         //      export runs during request handling, so this is available there.
         // Either path makes delivery reliable on workerd/OpenNext with no app hook.
-        // The `pending` set + `flushHeystack()` remain as the explicit fallback.
+        // The `pending` set + `flushHeystack()` remain as the explicit fallback;
+        // when neither handoff lands we say so once per isolate (see below).
+        const handoff = { borrowed: false };
         if (this.waitUntil) {
             try {
                 this.waitUntil(p);
+                handoff.borrowed = true;
             }
             catch (error) {
                 this.warnWaitUntilFailed("explicit waitUntil", error);
@@ -681,21 +761,88 @@ export class HeystackSpanExporter {
             // available; otherwise await the in-flight accessor load so even those
             // early exports get handed to waitUntil once it resolves. `p` is already
             // in `pending`, so a manual `flushHeystack()` covers it regardless.
-            this.handOffToCloudflareContext(p);
+            this.handOffToCloudflareContext(p, handoff);
         }
+        if (!handoff.borrowed) {
+            // Fallback pending-set mode: once THIS export settles with no handoff,
+            // raise the one-per-isolate advisory (suppressed for manual-flush users).
+            void p.then(() => warnIfNoHandoffOnce());
+        }
+    }
+    /**
+     * POST the batch with ONE bounded automatic retry for network errors / 429 /
+     * 5xx. Honours `Retry-After` (seconds form) on 429 within the total backoff
+     * cap; after retries are exhausted it preserves plain FAILED semantics via
+     * `resultCallback`. The returned promise never rejects.
+     */
+    postWithRetry(doFetch, body, resultCallback) {
+        let budgetLeft = RETRY_TOTAL_CAP_MS;
+        let retryAfterSeconds;
+        return (async () => {
+            let lastError;
+            for (let attempt = 0; attempt < EXPORT_MAX_ATTEMPTS; attempt++) {
+                if (attempt > 0) {
+                    const delay = nextRetryDelayMs(budgetLeft, retryAfterSeconds);
+                    budgetLeft -= delay;
+                    await sleep(delay);
+                }
+                let retryable = false;
+                try {
+                    const res = await context.with(suppressTracing(context.active()), () => doFetch(this.url, { method: "POST", headers: this.headers, body }));
+                    if (res.ok) {
+                        resultCallback({ code: ExportResultCode.SUCCESS });
+                        return;
+                    }
+                    lastError = new Error(`Heystack ingest responded ${res.status} ${res.statusText}`);
+                    retryable = res.status === 429 || res.status >= 500;
+                    if (res.status === 429) {
+                        retryAfterSeconds = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                    }
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    retryable = true;
+                }
+                if (!retryable)
+                    break;
+            }
+            resultCallback({
+                code: ExportResultCode.FAILED,
+                error: lastError ?? new Error("Heystack export failed"),
+            });
+        })();
+    }
+    /** Reserve a tracked slot synchronously before starting any network work. */
+    reservePending() {
+        if (this.pending.size >= MAX_PENDING_EXPORTS)
+            return undefined;
+        let release;
+        const pending = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.pending.add(pending);
+        void pending.then(() => {
+            this.pending.delete(pending);
+        });
+        return { pending, release };
     }
     /**
      * Hand `p` to the OpenNext Cloudflare request context's `ctx.waitUntil`.
      * Resolves the accessor first (awaiting its in-flight load if needed) so an
      * export that fired before the dynamic import settled is still covered.
+     * Sets `outcome.borrowed` when (and only when) a real `waitUntil` received
+     * `p` — the signal the no-handoff advisory keys off.
      */
-    handOffToCloudflareContext(p) {
+    handOffToCloudflareContext(p, outcome) {
         const attempt = () => {
             if (!_getCloudflareContext)
                 return;
             try {
                 const cf = _getCloudflareContext();
-                cf?.ctx?.waitUntil?.(p);
+                if (cf?.ctx?.waitUntil) {
+                    cf.ctx.waitUntil(p);
+                    outcome.borrowed = true;
+                }
             }
             catch (error) {
                 // #15: a real failure inside getCloudflareContext (e.g. called outside a
@@ -726,9 +873,9 @@ export class HeystackSpanExporter {
             "unless you call flushHeystack() or pass an explicit waitUntil.");
     }
     shutdown() {
-        return this.forceFlush().then(() => {
-            this.shutdownState = true;
-        });
+        // Reject new work immediately, then drain everything admitted beforehand.
+        this.shutdownState = true;
+        return this.forceFlush();
     }
     /**
      * Resolve only once every in-flight export fetch has settled. This is the
@@ -737,7 +884,11 @@ export class HeystackSpanExporter {
      * `flushHeystack` and `instrument`).
      */
     async forceFlush() {
-        await Promise.allSettled([...this.pending]);
+        // Exports can start from another callback while an earlier snapshot settles.
+        // Continue until the tracked set is actually quiescent.
+        while (this.pending.size > 0) {
+            await Promise.allSettled([...this.pending]);
+        }
     }
 }
 function nativeTracingFromContext() {
@@ -750,10 +901,8 @@ function nativeTracingFromContext() {
  */
 class NativeSpanAdapter {
     nativeSpan;
-    autoEnd;
-    constructor(nativeSpan, autoEnd) {
+    constructor(nativeSpan) {
         this.nativeSpan = nativeSpan;
-        this.autoEnd = autoEnd;
     }
     spanContext() { return INVALID_SPAN_CONTEXT; }
     setAttribute(key, value) {
@@ -804,10 +953,7 @@ class NativeSpanAdapter {
         return this;
     }
     updateName(_name) { return this; }
-    end(_endTime) {
-        if (!this.autoEnd)
-            this.nativeSpan.end();
-    }
+    end(_endTime) { }
     isRecording() { return this.nativeSpan.isTraced; }
     recordException(exception, _time) {
         const error = exception instanceof Error ? exception : new Error(String(exception));
@@ -842,7 +988,7 @@ function setNativeRequestAttributes(span, config, req) {
 async function runNativeSpan(nativeTracing, name, attrs, fn) {
     ensureContextManager();
     return nativeTracing.enterSpan(name, async (nativeSpan) => {
-        const adapter = new NativeSpanAdapter(nativeSpan, true);
+        const adapter = new NativeSpanAdapter(nativeSpan);
         for (const [key, value] of Object.entries(attrs)) {
             if (value !== undefined)
                 adapter.setAttribute(key, value);
@@ -899,9 +1045,9 @@ function getALS() {
  * context across `await` boundaries — child spans created after an `await`
  * inside a handler are correctly parented to the request's root span.
  *
- * WinterCG-safe: it does NOT import `node:async_hooks`; instead it uses the
- * ALS global that the runtime exposes. Falls back to `SyncStackContextManager`
- * when the global is absent (Deno, Bun without globals, etc.).
+ * WinterCG-safe: it does NOT import the Node-only async_hooks builtin; instead
+ * it uses the ALS global that the runtime exposes. Falls back to
+ * `SyncStackContextManager` when the global is absent (Deno, Bun without globals, etc.).
  */
 export class AlsContextManager {
     _als;
@@ -1022,10 +1168,12 @@ function ensureGlobalProvider(config) {
  * FLUSH: on Next-on-OpenNext (where `@opennextjs/cloudflare` is present) the
  * exporter automatically borrows the Cloudflare request context's
  * `ctx.waitUntil` so the export POST completes before the isolate is torn down
- * — no app hook needed. For other workerd setups without it, call
- * `flushHeystack()` (which awaits the export fetch) from a response hook, hand
- * it to `ctx.waitUntil(flushHeystack())`, or pass an explicit `waitUntil` in
- * the config (highest priority). Returns the provider.
+ * — no app hook needed. For other workerd setups without it, wrap your
+ * handler's ExecutionContext with {@link wrapExecutionContext} (every
+ * `ctx.waitUntil` then also schedules the export drain), call `flushHeystack()`
+ * (which awaits the export fetch) from a response hook, hand it to
+ * `ctx.waitUntil(flushHeystack())`, or pass an explicit `waitUntil` in the
+ * config (highest priority). Returns the provider.
  */
 export function initHeystackWorkers(config) {
     return ensureGlobalProvider(config);
@@ -1039,6 +1187,7 @@ export function initHeystackWorkers(config) {
  * isolate is torn down. Best-effort no-op if no provider is registered.
  */
 export async function flushHeystack() {
+    markManualFlushObserved();
     if (!_provider)
         return;
     if (typeof _provider.forceFlush === "function") {
@@ -1048,10 +1197,62 @@ export async function flushHeystack() {
     // drain the exporter's in-flight POSTs explicitly.
     await _provider.heystackExporter.forceFlush();
 }
+/**
+ * Wrap a Worker `ExecutionContext` so EVERY `ctx.waitUntil(promise)` ALSO
+ * schedules the exporter drain race after that promise settles (provider +
+ * in-flight POSTs, raced against an 8s timeout so a hung ingest can't pin the
+ * isolate). Use on
+ * `initHeystackWorkers()` / `createTracerProvider()` setups that don't go
+ * through `instrument()` (which wires the same drain internally):
+ *
+ *   export default {
+ *     async fetch(req, env, ctx) {
+ *       ctx = wrapExecutionContext(ctx);
+ *       return handle(req, env, ctx); // any waitUntil you do flushes exports
+ *     },
+ *   };
+ *
+ * Every other present or future ExecutionContext member is forwarded unchanged
+ * with the real host object as its receiver. Safe to call when tracing isn't
+ * initialised — the drain scheduling simply no-ops.
+ */
+function wrapExecutionContextWithProvider(ctx, configuredProvider) {
+    const waitUntil = (promise) => {
+        ctx.waitUntil(promise);
+        const provider = configuredProvider ?? _provider;
+        if (!provider)
+            return;
+        // Background work can create spans after awaits. Start its drain only once
+        // that work settles; a concurrent drain can finish before those spans exist.
+        ctx.waitUntil(promise
+            .catch(() => undefined)
+            .then(() => drainWithTimeout(provider)));
+    };
+    const passThroughOnException = () => {
+        ctx.passThroughOnException();
+    };
+    return new Proxy(ctx, {
+        get(target, property) {
+            if (property === "waitUntil")
+                return waitUntil;
+            if (property === "passThroughOnException")
+                return passThroughOnException;
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+        set(target, property, value) {
+            return Reflect.set(target, property, value, target);
+        },
+    });
+}
+export function wrapExecutionContext(ctx) {
+    return wrapExecutionContextWithProvider(ctx);
+}
 /** Reset the singleton global provider. Internal/testing helper. */
 export function __resetProvider() {
     _provider = null;
     _remoteSamplingKicked = false;
+    requestDrainWired = false;
 }
 /** Guard: the remote sampling config GET fires at most once per isolate. */
 let _remoteSamplingKicked = false;
@@ -1062,9 +1263,11 @@ function warnOnceNoKey() {
     warnedNoKey = true;
     console.warn("[heystack] HEYSTACK_API_KEY not set — Workers tracing disabled, handler runs untraced.");
 }
-/** Reset the once-only no-key warning. Internal/testing helper. */
+/** Reset the once-only warnings. Internal/testing helper. */
 export function __resetWarnings() {
     warnedNoKey = false;
+    warnedNoHandoff = false;
+    manualFlushObserved = false;
 }
 export function instrument(handler, config) {
     // Resolve the API key + set up (once) the global provider. Returns null when
@@ -1088,31 +1291,15 @@ export function instrument(handler, config) {
             sampling: config.sampling,
             ai: config.ai,
         });
+        // instrument() wires a per-request drain (see `drain` below), so exports on
+        // this path are reliably flushed — the no-handoff advisory must stay quiet.
+        requestDrainWired = true;
         return { provider, tracer: trace.getTracer("heystack") };
     };
     // Drain BOTH the provider's span processor AND the exporter's in-flight fetch
-    // via ctx.waitUntil. Awaiting only provider.forceFlush() would return before
-    // the export POST completes, letting the isolate be torn down and silently
-    // dropping the trace.
-    //
-    // #25: the drain is raced against an ~8s timeout so a hung forceFlush (e.g. an
-    // ingest that never responds) can't pin the isolate until the platform CPU
-    // timeout kills it. On timeout we stop waiting; the POST is still in-flight and
-    // may yet complete, we just don't block the isolate on it indefinitely.
-    const DRAIN_TIMEOUT_MS = 8_000;
+    // via ctx.waitUntil, raced against an ~8s timeout (see drainWithTimeout, #25).
     const drain = (provider, ctx) => {
-        const drained = (async () => {
-            await provider.forceFlush().catch(() => { });
-            await provider.heystackExporter.forceFlush().catch(() => { });
-        })();
-        let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(resolve, DRAIN_TIMEOUT_MS);
-        });
-        ctx.waitUntil(Promise.race([drained, timeout]).finally(() => {
-            if (timer)
-                clearTimeout(timer);
-        }));
+        ctx.waitUntil(drainWithTimeout(provider));
     };
     // Start from a shallow copy so EVERY sibling handler (tail, email, …) is
     // forwarded untouched; we only override fetch/queue/scheduled below.
@@ -1207,7 +1394,7 @@ export function instrument(handler, config) {
             }
             // FR5: response header carrying THIS span's trace + span id.
             const sc = span.spanContext();
-            const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+            const traceparent = makeTraceparent(sc);
             // The context with THIS request's SERVER span active. Used both to run the
             // handler and as an explicit parent fallback for binding spans.
             const serverCtx = trace.setSpan(startCtx, span);
@@ -1235,8 +1422,64 @@ export function instrument(handler, config) {
                     select: config.instrumentBindings,
                 });
             }
+            let finished = false;
+            const abortSignal = req.signal;
+            let responseStatus;
+            const finishSpan = (outcome, error) => {
+                if (finished)
+                    return;
+                finished = true;
+                abortSignal?.removeEventListener("abort", onAbort);
+                try {
+                    if (outcome === "aborted") {
+                        span.setAttribute("heystack.aborted", true);
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: "client stopped reading before the response completed",
+                        });
+                    }
+                    else if (outcome === "error") {
+                        const recorded = error instanceof Error ? error : new Error(String(error));
+                        span.recordException(recorded);
+                        span.setStatus({ code: SpanStatusCode.ERROR, message: recorded.message });
+                    }
+                    else {
+                        span.setStatus({
+                            code: responseStatus !== undefined && (responseStatus === 0 || responseStatus >= 500)
+                                ? SpanStatusCode.ERROR
+                                : SpanStatusCode.UNSET,
+                        });
+                    }
+                    span.end();
+                }
+                catch {
+                    // Telemetry must not change response delivery or error propagation.
+                }
+                try {
+                    drain(provider, ctx);
+                }
+                catch {
+                    // A rejected host waitUntil handoff must not break the response stream.
+                }
+            };
+            const onAbort = () => finishSpan("aborted");
             try {
-                const response = await context.with(serverCtx, () => originalFetch(req, handlerEnv, ctx));
+                const response = await context.with(serverCtx, () => originalFetch(req, handlerEnv, wrapExecutionContextWithProvider(ctx, provider)));
+                responseStatus = response.status;
+                if (abortSignal && !abortSignal.aborted) {
+                    abortSignal.addEventListener("abort", onAbort, { once: true });
+                }
+                else if (abortSignal?.aborted) {
+                    finishSpan("aborted");
+                }
+                // Response.error() has status 0 and immutable network-error semantics.
+                // Reconstructing it is invalid (ResponseInit only accepts 200-599), and
+                // there is no response header surface on which to inject traceparent.
+                if (response.status === 0) {
+                    span.setAttribute("http.response.status_code", response.status);
+                    finishSpan("success");
+                    return response;
+                }
                 // WebSocket / connection upgrades: a 101 Switching Protocols response
                 // carries a live server-side `webSocket` that the Workers Runtime hands
                 // to the client ONLY if that exact Response object is returned. Rebuilding
@@ -1248,64 +1491,66 @@ export function instrument(handler, config) {
                 // signal; `status === 101` is a belt-and-braces fallback.
                 if (response.webSocket || response.status === 101) {
                     span.setAttribute("http.response.status_code", response.status);
-                    span.setStatus({ code: SpanStatusCode.UNSET });
-                    span.end();
-                    drain(provider, ctx);
+                    finishSpan("success");
                     return response;
                 }
                 const headers = new Headers(response.headers);
                 headers.set("traceparent", traceparent);
                 appendExposeHeader(headers, "traceparent");
                 span.setAttribute("http.response.status_code", response.status);
-                const finalize = () => {
-                    span.setStatus({
-                        code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
-                    });
-                    span.end();
-                    drain(provider, ctx);
-                };
                 // No body to stream → finalize now (redirects, 204/304, etc.).
                 if (!response.body) {
-                    finalize();
+                    finishSpan("success");
                     return new Response(null, {
                         status: response.status,
                         statusText: response.statusText,
                         headers,
                     });
                 }
-                // FR1: keep the span open until the streamed body drains; the first
-                // chunk records time-to-first-byte. `finished` guards double-finalize.
+                // FR1: pull one chunk at a time from the original body. This preserves
+                // streaming/backpressure without buffering, while observing all three
+                // terminal paths: clean EOF, source error, and consumer cancellation.
                 let firstByte = false;
-                let finished = false;
-                const monitor = new TransformStream({
-                    transform(chunk, controller) {
-                        if (!firstByte) {
-                            firstByte = true;
-                            span.addEvent("first_byte");
+                let consumerCancelled = false;
+                const reader = response.body.getReader();
+                const monitoredBody = new ReadableStream({
+                    async pull(controller) {
+                        try {
+                            const result = await reader.read();
+                            if (consumerCancelled)
+                                return;
+                            if (result.done) {
+                                finishSpan("success");
+                                controller.close();
+                                return;
+                            }
+                            if (!firstByte) {
+                                firstByte = true;
+                                span.addEvent("first_byte");
+                            }
+                            controller.enqueue(result.value);
+                        }
+                        catch (error) {
+                            if (consumerCancelled)
+                                return;
+                            finishSpan("error", error);
+                            controller.error(error);
                         }
-                        controller.enqueue(chunk);
                     },
-                    flush() {
-                        if (finished)
-                            return;
-                        finished = true;
-                        finalize();
+                    cancel(reason) {
+                        consumerCancelled = true;
+                        finishSpan("aborted", reason);
+                        return reader.cancel(reason);
                     },
                 });
-                return new Response(response.body.pipeThrough(monitor), {
+                return new Response(monitoredBody, {
                     status: response.status,
                     statusText: response.statusText,
                     headers,
                 });
             }
             catch (error) {
-                span.recordException(error instanceof Error ? error : new Error(String(error)));
-                span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: error instanceof Error ? error.message : String(error),
-                });
-                span.end();
-                drain(provider, ctx);
+                finishSpan("error", error);
                 throw error;
             }
         };
@@ -1316,6 +1561,8 @@ export function instrument(handler, config) {
             const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
             if (nativeTracing) {
                 ensureFetchInstrumentation("", config.ai ?? {});
+                // Native mode: Cloudflare owns queue spans — pass the ORIGINAL batch
+                // through untouched so platform objects keep their identity.
                 return runNativeSpan(nativeTracing, `heystack.queue ${batch.queue}`, {
                     "service.name": config.service,
                     "messaging.batch.message_count": batch.messages.length,
@@ -1336,8 +1583,24 @@ export function instrument(handler, config) {
                     "messaging.destination.name": batch.queue,
                 },
             });
+            // The request's CONSUMER context, captured per-batch as an explicit parent
+            // fallback (same rationale as the binding-span serverCtx below): on
+            // workerd WITHOUT nodejs_compat a message ack'd after an `await` would
+            // otherwise orphan into its own single-span trace.
+            const consumerCtx = trace.setSpan(context.active(), span);
+            const startMessageSpan = (name, attrs) => {
+                const active = context.active();
+                const parentCtx = trace.getSpan(active) ? active : consumerCtx;
+                return tracer.startSpan(name, { attributes: attrs }, parentCtx);
+            };
+            // Per-message visibility: the wrapper hands the WHOLE batch to user code
+            // in one call (splitting it would change retry/ack semantics), so the true
+            // per-message unit of work observable here is the explicit
+            // `msg.ack()` / `msg.retry()` decision — each gets a cheap INTERNAL child
+            // span when the consumer uses per-message control flow.
+            const tracedBatch = wrapQueueMessageBatch(batch, startMessageSpan);
             try {
-                await context.with(trace.setSpan(context.active(), span), () => originalQueue(batch, env, ctx));
+                await context.with(consumerCtx, () => originalQueue(tracedBatch, env, wrapExecutionContextWithProvider(ctx, provider)));
                 span.setStatus({ code: SpanStatusCode.UNSET });
                 span.end();
                 drain(provider, ctx);
@@ -1379,7 +1642,90 @@ export function instrument(handler, config) {
                 },
             });
             try {
-                await context.with(trace.setSpan(context.active(), span), () => originalScheduled(controller, env, ctx));
+                await context.with(trace.setSpan(context.active(), span), () => originalScheduled(controller, env, wrapExecutionContextWithProvider(ctx, provider)));
+                span.setStatus({ code: SpanStatusCode.UNSET });
+                span.end();
+                drain(provider, ctx);
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                drain(provider, ctx);
+                throw error;
+            }
+        };
+    }
+    const originalEmail = handler.email?.bind(handler);
+    if (originalEmail) {
+        wrapped.email = async (message, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            // PRIVACY: only from/to DOMAINS + envelope size are recorded — never the
+            // full addresses and never any message content.
+            const { name: emailSpanName, attrs: emailAttrs } = emailHandlerAttrs(message);
+            if (nativeTracing) {
+                return runNativeSpan(nativeTracing, `heystack.${emailSpanName}`, {
+                    "service.name": config.service,
+                    ...emailAttrs,
+                    "service.version": config.version,
+                    "service.build": config.build,
+                }, () => originalEmail(message, env, ctx));
+            }
+            const s = setup(env);
+            if (!s)
+                return originalEmail(message, env, ctx);
+            const { provider, tracer } = s;
+            const span = tracer.startSpan(emailSpanName, {
+                kind: SpanKind.SERVER,
+                attributes: emailAttrs,
+            });
+            try {
+                await context.with(trace.setSpan(context.active(), span), () => originalEmail(message, env, wrapExecutionContextWithProvider(ctx, provider)));
+                span.setStatus({ code: SpanStatusCode.UNSET });
+                span.end();
+                drain(provider, ctx);
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.end();
+                drain(provider, ctx);
+                throw error;
+            }
+        };
+    }
+    const originalTail = handler.tail?.bind(handler);
+    if (originalTail) {
+        wrapped.tail = async (events, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            // PRIVACY: only the event COUNT is recorded — tail payloads can contain
+            // request URLs, headers and console output; none of it is captured.
+            const count = Array.isArray(events) ? events.length : 0;
+            const attrs = { "cloudflare.tail.event_count": count };
+            if (nativeTracing) {
+                return runNativeSpan(nativeTracing, "heystack.tail", {
+                    "service.name": config.service,
+                    ...attrs,
+                    "service.version": config.version,
+                    "service.build": config.build,
+                }, () => originalTail(events, env, ctx));
+            }
+            const s = setup(env);
+            if (!s)
+                return originalTail(events, env, ctx);
+            const { provider, tracer } = s;
+            const span = tracer.startSpan("tail", {
+                kind: SpanKind.INTERNAL,
+                attributes: attrs,
+            });
+            try {
+                await context.with(trace.setSpan(context.active(), span), () => originalTail(events, env, wrapExecutionContextWithProvider(ctx, provider)));
                 span.setStatus({ code: SpanStatusCode.UNSET });
                 span.end();
                 drain(provider, ctx);
@@ -1398,13 +1744,515 @@ export function instrument(handler, config) {
     }
     return wrapped;
 }
+// ---------------------------------------------------------------------------
+// Queue consumer: per-message ack/retry child spans
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a queue batch so each message's explicit `ack()` / `retry()` emits a
+ * cheap INTERNAL child span. The batch itself is handed to user code in ONE
+ * call — the wrapper cannot split it without changing retry/ack semantics — so
+ * `queue message process` spans are deliberately NOT emitted; when a consumer
+ * uses per-message control flow these ack/retry spans are the true per-message
+ * unit of work. Consumers that never call ack()/retry() simply see no extra
+ * spans. Non-wrapped members (ackAll/retryAll/queue/id/body/timestamp) fall
+ * through to the real platform objects with correct receivers.
+ */
+function wrapQueueMessageBatch(batch, startSpan) {
+    const source = batch.messages;
+    if (!Array.isArray(source))
+        return batch;
+    const messages = source.map((m) => wrapQueueMessage(m, startSpan));
+    return new Proxy(batch, {
+        get(t, prop, _receiver) {
+            if (prop === "messages")
+                return messages;
+            const val = Reflect.get(t, prop, t);
+            return typeof val === "function" ? val.bind(t) : val;
+        },
+    });
+}
+function wrapQueueMessage(message, startSpan) {
+    if (!message || typeof message !== "object")
+        return message;
+    return new Proxy(message, {
+        get(t, prop, _receiver) {
+            if (prop === "ack" || prop === "retry") {
+                const orig = t[prop];
+                if (typeof orig !== "function")
+                    return orig;
+                return (...args) => {
+                    // Bind to the REAL platform message (brand-check-safe receiver).
+                    if (isTracingSuppressed(context.active())) {
+                        orig.apply(t, args);
+                        return;
+                    }
+                    const attrs = { "messaging.system": "cloudflare_queues" };
+                    if (typeof t.attempts === "number")
+                        attrs["messaging.attempt"] = t.attempts;
+                    if (typeof t.body === "string")
+                        attrs["messaging.message.body.size"] = t.body.length;
+                    const span = startSpan(`queue message ${prop}`, attrs);
+                    try {
+                        orig.apply(t, args);
+                    }
+                    catch (error) {
+                        try {
+                            span.recordException(error instanceof Error ? error : new Error(String(error)));
+                            span.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                        catch {
+                            // Preserve the platform method's original exception.
+                        }
+                        throw error;
+                    }
+                    finally {
+                        try {
+                            span.end();
+                        }
+                        catch {
+                            // Queue decisions must remain synchronous platform operations.
+                        }
+                    }
+                };
+            }
+            const val = Reflect.get(t, prop, t);
+            return typeof val === "function" ? val.bind(t) : val;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Email handler span naming/attrs (privacy-preserving)
+// ---------------------------------------------------------------------------
+/**
+ * Extract the DOMAIN of an email address, or "" for anything malformed.
+ * Deliberately never returns the local part — full addresses are PII.
+ */
+function emailDomain(address) {
+    if (typeof address !== "string")
+        return "";
+    const at = address.lastIndexOf("@");
+    if (at <= 0 || at === address.length - 1)
+        return "";
+    return address.slice(at + 1).toLowerCase();
+}
+/** SERVER-span name + attributes for an email handler invocation. */
+function emailHandlerAttrs(message) {
+    const fromDomain = emailDomain(message?.from);
+    const toDomain = emailDomain(message?.to);
+    const attrs = {};
+    if (fromDomain)
+        attrs["cloudflare.email.from_domain"] = fromDomain;
+    if (toDomain)
+        attrs["cloudflare.email.to_domain"] = toDomain;
+    const size = message?.rawSize;
+    if (typeof size === "number" && Number.isFinite(size)) {
+        attrs["cloudflare.email.raw_size_bytes"] = size;
+    }
+    return { name: fromDomain ? `email ${fromDomain}` : "email", attrs };
+}
+function classStartSpan(opts) {
+    return (opts.startSpan ??
+        ((name, attrs, kind, ctx) => trace.getTracer("heystack").startSpan(name, { attributes: attrs, kind }, ctx ?? context.active())));
+}
+/**
+ * Keep the isolate alive until pending exports drain: hand `flushHeystack()`
+ * to the invocation's DurableObjectState `waitUntil`. Best-effort no-op when no
+ * state/waitUntil is available (e.g. unit tests).
+ */
+function scheduleStateFlush(state) {
+    const waitUntil = state
+        ?.waitUntil;
+    if (typeof waitUntil !== "function")
+        return;
+    try {
+        waitUntil.call(state, flushHeystack());
+    }
+    catch {
+        // A failing waitUntil must never break the wrapped handler.
+    }
+}
+/** INTERNAL child spans for DurableObjectStorage get/put/delete/list ops. */
+function wrapDurableObjectStorage(storage, startSpan) {
+    const wrapOp = (op) => async (...args) => {
+        const underlying = storage[op];
+        if (typeof underlying !== "function")
+            return undefined;
+        if (isTracingSuppressed(context.active())) {
+            return underlying.apply(storage, args);
+        }
+        const attrs = {};
+        const first = args[0];
+        if (typeof first === "string") {
+            attrs["cloudflare.do.storage.key"] = first;
+        }
+        else if (Array.isArray(first)) {
+            attrs["cloudflare.do.storage.key_count"] = first.length;
+        }
+        else if (op === "list" &&
+            first &&
+            typeof first === "object" &&
+            typeof first.limit === "number") {
+            attrs["cloudflare.do.storage.limit"] = first.limit;
+        }
+        const span = startSpan(`DO storage ${op}`, attrs, SpanKind.INTERNAL);
+        return runWithSpan(span, () => Promise.resolve(underlying.apply(storage, args)));
+    };
+    // A dedicated proxy (not makeProxy) because `storage` is a VALUE property on
+    // the state object, not a method — handlers there must be getters.
+    return new Proxy(storage, {
+        get(t, prop, _receiver) {
+            const val = Reflect.get(t, prop, t);
+            if ((prop === "get" || prop === "put" || prop === "delete" || prop === "list") && typeof val === "function") {
+                return wrapOp(prop);
+            }
+            return typeof val === "function" ? val.bind(t) : val;
+        },
+    });
+}
+/** Proxy a DurableObjectState so `state.storage` resolves to the traced proxy. */
+function wrapDurableObjectState(state, startSpan) {
+    if (!state || typeof state !== "object")
+        return state;
+    const s = state;
+    if (!s.storage || typeof s.storage !== "object")
+        return state;
+    const tracedStorage = wrapDurableObjectStorage(s.storage, startSpan);
+    return new Proxy(s, {
+        get(t, prop, _receiver) {
+            if (prop === "storage")
+                return tracedStorage;
+            const val = Reflect.get(t, prop, t);
+            return typeof val === "function" ? val.bind(t) : val;
+        },
+    });
+}
+/** Prototype methods that are wrapped specially (never treated as RPC). */
+const DO_LIFECYCLE_METHODS = new Set(["fetch", "alarm", "constructor"]);
+const MAX_DO_RPC_METHODS = 32;
+/**
+ * Decorate a Durable Object class:
+ * - constructor: wraps the incoming `state` so `state.storage` operations emit
+ *   INTERNAL child spans (`DO storage get|put|delete|list`) with key/count attrs.
+ * - `fetch()`: SERVER span named `<METHOD> <path>` (like instrument()'s fetch
+ *   wrapper), continuing an inbound W3C traceparent, recording status/duration.
+ * - `alarm()`: INTERNAL span.
+ * - RPC prototype methods: SERVER span `DO rpc <method>` with rpc.method attrs.
+ *
+ * Every root span schedules flushHeystack() via `state.waitUntil` so exports
+ * complete before isolate teardown. Instance arrow-function methods assigned in
+ * the constructor are not enumerable on the prototype and stay unwrapped.
+ *
+ *   export class Counter extends DurableObject {
+ *     // ...
+ *   }
+ *   export const Counter = wrapDurableObjectClass(BaseCounter); // or decorate in place
+ */
+export function wrapDurableObjectClass(cls, opts = {}) {
+    const Base = cls;
+    const startSpan = classStartSpan(opts);
+    const proto = Base.prototype;
+    const origFetch = proto.fetch;
+    const origAlarm = proto.alarm;
+    // Enumerate the RPC surface (prototype chain, lifecycle handlers excluded).
+    const rpcMethods = [];
+    try {
+        let p = Base.prototype;
+        for (let depth = 0; depth < 5 && p && p !== Object.prototype && rpcMethods.length < MAX_DO_RPC_METHODS; depth++) {
+            for (const key of Object.getOwnPropertyNames(p)) {
+                if (DO_LIFECYCLE_METHODS.has(key))
+                    continue;
+                if (!rpcMethods.includes(key) && typeof proto[key] === "function") {
+                    rpcMethods.push(key);
+                    if (rpcMethods.length >= MAX_DO_RPC_METHODS)
+                        break;
+                }
+            }
+            p = Object.getPrototypeOf(p);
+        }
+    }
+    catch {
+        // Best-effort enumeration — a hostile getter must never break decoration.
+    }
+    class Wrapped extends Base {
+        /** Raw (unwrapped) state captured for flush scheduling. */
+        __heystackState;
+        constructor(...args) {
+            super(...args.map((arg, i) => i === 0 ? wrapDurableObjectState(arg, startSpan) : arg));
+            this.__heystackState = args[0];
+        }
+    }
+    if (typeof origFetch === "function") {
+        Wrapped.prototype.fetch = async function (request) {
+            if (isTracingSuppressed(context.active())) {
+                return origFetch.call(this, request);
+            }
+            // Continue an inbound W3C traceparent so caller→DO is one distributed trace.
+            let startCtx = context.active();
+            const parent = parseTraceparent(request.headers.get("traceparent"));
+            if (parent) {
+                startCtx = trace.setSpanContext(startCtx, {
+                    traceId: parent.traceId,
+                    spanId: parent.spanId,
+                    traceFlags: parent.traceFlags,
+                    isRemote: true,
+                });
+            }
+            let url;
+            try {
+                url = new URL(request.url);
+            }
+            catch {
+                url = new URL("https://durable-object.invalid/");
+            }
+            const span = startSpan(`${request.method} ${url.pathname}`, {
+                "http.request.method": request.method,
+                "url.path": url.pathname,
+                "server.address": url.host,
+            }, SpanKind.SERVER, startCtx);
+            try {
+                const response = (await context.with(trace.setSpan(startCtx, span), () => origFetch.call(this, request)));
+                span.setAttribute("http.response.status_code", response.status);
+                span.setStatus({
+                    code: response.status >= 500 ? SpanStatusCode.ERROR : SpanStatusCode.UNSET,
+                });
+                return response;
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+                scheduleStateFlush(this.__heystackState);
+            }
+        };
+    }
+    if (typeof origAlarm === "function") {
+        Wrapped.prototype.alarm = async function (...args) {
+            if (isTracingSuppressed(context.active())) {
+                return origAlarm.apply(this, args);
+            }
+            const span = startSpan("DO alarm", {}, SpanKind.INTERNAL);
+            try {
+                return await context.with(trace.setSpan(context.active(), span), () => origAlarm.apply(this, args));
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+                scheduleStateFlush(this.__heystackState);
+            }
+        };
+    }
+    for (const method of rpcMethods) {
+        const orig = proto[method];
+        Wrapped.prototype[method] = async function (...args) {
+            if (isTracingSuppressed(context.active())) {
+                return orig.apply(this, args);
+            }
+            const span = startSpan(`DO rpc ${method}`, {
+                "rpc.system": "cloudflare.durable_object",
+                "rpc.method": method,
+            }, SpanKind.SERVER);
+            try {
+                return await context.with(trace.setSpan(context.active(), span), () => orig.apply(this, args));
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+                scheduleStateFlush(this.__heystackState);
+            }
+        };
+    }
+    return Wrapped;
+}
+// ---------------------------------------------------------------------------
+// Workflows ENTRYPOINT class instrumentation
+// ---------------------------------------------------------------------------
+/** Step methods that are async WAITS — traced as short marker spans, never held open. */
+const WORKFLOW_WAIT_METHODS = ["sleep", "sleepUntil", "waitForEvent", "waitForName"];
+/** Marker-span attributes for a wait call (duration/timestamp only — no payload). */
+function workflowWaitAttrs(method, args) {
+    if (method === "sleep" && args.length > 1 && args[1] != null) {
+        return { "cloudflare.workflow.sleep_duration": String(args[1]) };
+    }
+    if (method === "sleepUntil" && args.length > 1 && args[1] != null) {
+        const ts = args[1] instanceof Date ? args[1].toISOString() : String(args[1]);
+        return { "cloudflare.workflow.sleep_until": ts };
+    }
+    return undefined;
+}
+/** Privacy-safe attributes from Cloudflare's real WorkflowEvent contract. */
+function workflowRunAttrs(event) {
+    if (!event || typeof event !== "object")
+        return {};
+    const value = event;
+    const attrs = {};
+    if (typeof value.workflowName === "string") {
+        attrs["cloudflare.workflow.name"] = value.workflowName;
+    }
+    if (typeof value.instanceId === "string") {
+        attrs["cloudflare.workflow.instance_id"] = value.instanceId;
+    }
+    if (value.timestamp instanceof Date && Number.isFinite(value.timestamp.getTime())) {
+        attrs["cloudflare.workflow.timestamp"] = value.timestamp.toISOString();
+    }
+    if (value.schedule && typeof value.schedule === "object") {
+        if (typeof value.schedule.cron === "string") {
+            attrs["cloudflare.workflow.schedule.cron"] = value.schedule.cron;
+        }
+        if (typeof value.schedule.scheduledTime === "number" &&
+            Number.isFinite(value.schedule.scheduledTime)) {
+            attrs["cloudflare.workflow.schedule.scheduled_time"] = value.schedule.scheduledTime;
+        }
+    }
+    return attrs;
+}
+/**
+ * Wrap a WorkflowStep so `do(name, fn)` executes fn inside a step span while
+ * preserving engine semantics (we wrap FN and delegate to the real step.do —
+ * the workflow engine owns execution/caching across replays), and wait-style
+ * methods become short MARKER spans that end immediately after the wait is
+ * initiated (a workflow can suspend for minutes; holding a span open across a
+ * sleep would poison duration metrics).
+ */
+function wrapWorkflowStep(step, startSpan, state) {
+    const handlers = {};
+    if (typeof step.do === "function") {
+        handlers.do = (name, fn, ...rest) => {
+            if (isTracingSuppressed(context.active()) || typeof fn !== "function") {
+                return step.do(name, fn, ...rest);
+            }
+            return step.do(name, async (...fnArgs) => {
+                const span = startSpan(`step ${String(name)}`, {}, SpanKind.INTERNAL);
+                try {
+                    return await context.with(trace.setSpan(context.active(), span), () => Promise.resolve(fn(...fnArgs)));
+                }
+                catch (error) {
+                    span.recordException(error instanceof Error ? error : new Error(String(error)));
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    throw error;
+                }
+                finally {
+                    span.end();
+                }
+            }, ...rest);
+        };
+    }
+    for (const method of WORKFLOW_WAIT_METHODS) {
+        if (typeof step[method] !== "function")
+            continue;
+        handlers[method] = (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return step[method](...args);
+            }
+            const nameArg = typeof args[0] === "string" ? ` ${args[0]}` : "";
+            const span = startSpan(`workflow ${method}${nameArg}`, workflowWaitAttrs(method, args) ?? {}, SpanKind.INTERNAL);
+            try {
+                // Marker semantics: end the span synchronously after initiating the
+                // wait — the returned promise is awaited by the caller OUTSIDE the span.
+                return step[method](...args);
+            }
+            catch (error) {
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+                // The caller suspends only after this wrapper returns the wait promise,
+                // so hand the ended marker span to waitUntil before that can happen.
+                scheduleStateFlush(state);
+            }
+        };
+    }
+    return makeProxy(step, handlers);
+}
+/**
+ * Decorate a Cloudflare Workflows entrypoint class so its `run(event, step)`
+ * emits a `workflow run` INTERNAL span with workflow identity/schedule metadata
+ * (never payload content), and the handed-out
+ * step object's methods become traced versions (see {@link wrapWorkflowStep}):
+ * `step.do(name, fn)` → INTERNAL span named `step <name>` with success/error
+ * status (step retries manifest as whole-run replays by the engine and are not
+ * observable at this layer, so no retry attribute is emitted), and
+ * sleep/sleepUntil/waitForEvent/waitForName → short marker spans.
+ *
+ * Every completed run schedules flushHeystack() via the entrypoint state's
+ * `waitUntil` so exports survive isolate teardown.
+ */
+export function wrapWorkflowEntrypointClass(cls, opts = {}) {
+    const Base = cls;
+    const startSpan = classStartSpan(opts);
+    const origRun = Base.prototype.run;
+    if (typeof origRun !== "function")
+        return cls;
+    class Wrapped extends Base {
+        __heystackState;
+        constructor(...args) {
+            super(...args);
+            this.__heystackState = args[0];
+        }
+    }
+    Wrapped.prototype.run = async function (event, step, ...rest) {
+        if (isTracingSuppressed(context.active())) {
+            return origRun.call(this, event, step, ...rest);
+        }
+        const attrs = workflowRunAttrs(event);
+        const span = startSpan("workflow run", attrs, SpanKind.INTERNAL);
+        try {
+            return await context.with(trace.setSpan(context.active(), span), () => origRun.call(this, event, step && typeof step === "object"
+                ? wrapWorkflowStep(step, startSpan, this.__heystackState)
+                : step, ...rest));
+        }
+        catch (error) {
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+            scheduleStateFlush(this.__heystackState);
+        }
+    };
+    return Wrapped;
+}
 export async function withSpan(name, attrsOrFn, maybeFn) {
     const attrs = typeof attrsOrFn === "function" ? undefined : attrsOrFn;
     const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
     const nativeTracing = nativeTracingFromContext();
     if (nativeTracing) {
         return nativeTracing.enterSpan(name, async (nativeSpan) => {
-            const adapter = new NativeSpanAdapter(nativeSpan, true);
+            const adapter = new NativeSpanAdapter(nativeSpan);
             if (attrs)
                 adapter.setAttributes(attrs);
             const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);