@lostgradient/weft 0.2.0

package/dist/observability/propagation.d.ts

@@ -0,0 +1,121 @@
+/**
+ * W3C Trace Context propagation helpers.
+ *
+ * Implements parsing, formatting, and injection/extraction of the
+ * `traceparent` header as defined in the W3C Trace Context specification.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ * @module propagation
+ */
+/**
+ * Parsed W3C trace context fields from a `traceparent` header.
+ *
+ * @example
+ * ```ts
+ * import { formatTraceParent, type TraceContext } from '@lostgradient/weft/observability';
+ *
+ * const context: TraceContext = {
+ *   version: '00',
+ *   traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+ *   spanId: '00f067aa0ba902b7',
+ *   traceFlags: 1,
+ * };
+ * console.log(formatTraceParent(context));
+ * ```
+ */
+export interface TraceContext {
+    version: string;
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/**
+ * Parse a W3C traceparent header string.
+ *
+ * @example
+ * ```ts
+ * import { parseTraceParent } from '@lostgradient/weft';
+ *
+ * const ctx = parseTraceParent(
+ *   '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+ * );
+ * console.log(ctx?.traceId);  // '4bf92f3577b34da6a3ce929d0e0e4736'
+ * console.log(ctx?.traceFlags); // 1
+ * ```
+ */
+export declare function parseTraceParent(value: string): TraceContext | null;
+/**
+ * Format a TraceContext to a W3C traceparent string.
+ *
+ * @example
+ * ```ts
+ * import { formatTraceParent, generateTraceId, generateSpanId } from '@lostgradient/weft';
+ *
+ * const header = formatTraceParent({
+ *   version: '00',
+ *   traceId: generateTraceId(),
+ *   spanId: generateSpanId(),
+ *   traceFlags: 1,
+ * });
+ * console.log(header); // '00-<32hex>-<16hex>-01'
+ * ```
+ */
+export declare function formatTraceParent(context: TraceContext): string;
+/**
+ * Extract and parse a `traceparent` header from a headers map.
+ *
+ * @example
+ * ```ts
+ * import { extractTraceParent } from '@lostgradient/weft/observability';
+ *
+ * const headers = new Map([
+ *   ['traceparent', '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'],
+ * ]);
+ * console.log(extractTraceParent(headers)?.traceId);
+ * ```
+ */
+export declare function extractTraceParent(headers: Map<string, string>): TraceContext | null;
+/**
+ * Format and inject a `traceparent` header into a headers map.
+ *
+ * @example
+ * ```ts
+ * import { generateSpanId, generateTraceId, injectTraceParent } from '@lostgradient/weft/observability';
+ *
+ * const headers = new Map<string, string>();
+ * injectTraceParent(headers, {
+ *   version: '00',
+ *   traceId: generateTraceId(),
+ *   spanId: generateSpanId(),
+ *   traceFlags: 1,
+ * });
+ * console.log(headers.has('traceparent'));
+ * ```
+ */
+export declare function injectTraceParent(headers: Map<string, string>, context: TraceContext): void;
+/**
+ * Generate a random trace ID (32 hex chars / 16 bytes).
+ *
+ * @example
+ * ```ts
+ * import { generateTraceId } from '@lostgradient/weft';
+ *
+ * const traceId = generateTraceId();
+ * console.log(traceId.length);  // 32
+ * console.log(/^[0-9a-f]{32}$/.test(traceId)); // true
+ * ```
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a random span ID (16 hex chars / 8 bytes).
+ *
+ * @example
+ * ```ts
+ * import { generateSpanId } from '@lostgradient/weft';
+ *
+ * const spanId = generateSpanId();
+ * console.log(spanId.length);  // 16
+ * console.log(/^[0-9a-f]{16}$/.test(spanId)); // true
+ * ```
+ */
+export declare function generateSpanId(): string;

package/dist/observability/propagation.js

@@ -0,0 +1,41 @@
+function randomHex(byteCount) {
+  const bytes = new Uint8Array(byteCount);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+const TRACEPARENT_HEADER = "traceparent", TRACEPARENT_REGEX = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/, ALL_ZEROS_TRACE_ID = "00000000000000000000000000000000", ALL_ZEROS_SPAN_ID = "0000000000000000";
+export function parseTraceParent(value) {
+  const match = TRACEPARENT_REGEX.exec(value);
+  if (!match)
+    return null;
+  const [, version, traceId, spanId, flags] = match;
+  if (traceId === ALL_ZEROS_TRACE_ID)
+    return null;
+  if (spanId === ALL_ZEROS_SPAN_ID)
+    return null;
+  return {
+    version,
+    traceId,
+    spanId,
+    traceFlags: parseInt(flags, 16)
+  };
+}
+export function formatTraceParent(context) {
+  const flags = context.traceFlags.toString(16).padStart(2, "0");
+  return `${context.version}-${context.traceId}-${context.spanId}-${flags}`;
+}
+export function extractTraceParent(headers) {
+  const value = headers.get(TRACEPARENT_HEADER);
+  if (!value)
+    return null;
+  return parseTraceParent(value);
+}
+export function injectTraceParent(headers, context) {
+  headers.set(TRACEPARENT_HEADER, formatTraceParent(context));
+}
+export function generateTraceId() {
+  return randomHex(16);
+}
+export function generateSpanId() {
+  return randomHex(8);
+}

package/dist/observability/span-helpers.d.ts

@@ -0,0 +1,50 @@
+import type { OpenTelemetrySpan } from './no-op-telemetry';
+import type { InterceptionContext, ObservabilityState } from './types';
+export declare const DEFAULT_MAX_PAYLOAD_SIZE = 1024;
+export declare function serializePayload(input: unknown, maxSize: number): string;
+/** Extract error message from an unknown thrown value. */
+export declare function errorMessage(error: unknown): string;
+/** Convert an unknown thrown value to an Error for `recordException`. */
+export declare function toError(error: unknown): Error;
+/** Inject the traceparent header from a span's context into a headers map. */
+export declare function injectSpanContext(span: OpenTelemetrySpan, headers: Map<string, string>): void;
+export declare function applyCustomAttributes(state: ObservabilityState, span: OpenTelemetrySpan, interception: InterceptionContext): void;
+export declare function parentContextForWorkflow(state: ObservabilityState, workflowId: string): unknown;
+type SpanLifecycleState = Pick<ObservabilityState, 'SpanStatusCode'>;
+/**
+ * Run a sync body inside a span's lifecycle.
+ *
+ * On success, sets the span status to OK and invokes `onSuccess` (if
+ * provided) before ending the span. On failure, sets the status to ERROR,
+ * records the exception, and rethrows the original error by identity. The
+ * span is always ended exactly once via `finally`.
+ *
+ * `onSuccess` runs before `span.end()` so callers can record success-only
+ * side effects (metrics) in the same ordering they would inline. An
+ * exception thrown from `onSuccess` is not caught: it overwrites the OK
+ * status with an ERROR record and propagates to the caller.
+ */
+export declare function runWithSpan<T>(state: SpanLifecycleState, span: OpenTelemetrySpan, body: () => T, onSuccess?: (result: T) => void): T;
+/**
+ * Await an async body inside a span's lifecycle.
+ *
+ * Same semantics as {@link runWithSpan} but awaits `body` and accepts a
+ * `T | Promise<T>` return so call sites whose `next()` is typed as
+ * possibly-synchronous still type-check.
+ */
+export declare function runAsyncWithSpan<T>(state: SpanLifecycleState, span: OpenTelemetrySpan, body: () => T | Promise<T>, onSuccess?: (result: T) => void): Promise<T>;
+/**
+ * Yield* a generator body inside a span's lifecycle.
+ *
+ * Same span lifecycle as {@link runWithSpan}. The helper uses `yield* body()`,
+ * which forwards `.throw()` and `.return()` from the outer caller to the inner
+ * generator per the ECMAScript generator-delegation contract:
+ *
+ * - `.throw(error)` surfaces as an exception inside `yield*`, is caught by
+ *   this helper, and is recorded on the span as an error before the span ends.
+ * - `.return(value)` propagates as a normal completion: the helper's `finally`
+ *   ends the span, but the body is treated as cancelled — `onSuccess` does
+ *   not run and the span status is whatever was last set (typically unset).
+ */
+export declare function runGeneratorWithSpan<TYield, TReturn, TNext>(state: SpanLifecycleState, span: OpenTelemetrySpan, body: () => Generator<TYield, TReturn, TNext>, onSuccess?: (result: TReturn) => void): Generator<TYield, TReturn, TNext>;
+export {};

package/dist/observability/span-helpers.js

@@ -0,0 +1,83 @@
+import { injectTraceParent } from "./propagation.js";
+export const DEFAULT_MAX_PAYLOAD_SIZE = 1024;
+export function serializePayload(input, maxSize) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(input);
+  } catch {
+    serialized = String(input);
+  }
+  if (serialized.length > maxSize)
+    return serialized.slice(0, maxSize) + "...";
+  return serialized;
+}
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export function toError(error) {
+  return error instanceof Error ? error : Error(String(error));
+}
+export function injectSpanContext(span, headers) {
+  const ctx = span.spanContext();
+  injectTraceParent(headers, {
+    version: "00",
+    traceId: ctx.traceId,
+    spanId: ctx.spanId,
+    traceFlags: ctx.traceFlags
+  });
+}
+export function applyCustomAttributes(state, span, interception) {
+  const attributeExtractor = state.attributeExtractor;
+  if (!attributeExtractor)
+    return;
+  const custom = attributeExtractor(interception);
+  for (const [key, value] of Object.entries(custom))
+    span.setAttribute(key, value);
+}
+export function parentContextForWorkflow(state, workflowId) {
+  const rootEntry = state.workflowSpans.get(workflowId);
+  return rootEntry ? state.trace.setSpan(state.api.context.ROOT_CONTEXT, rootEntry.span) : state.api.context.ROOT_CONTEXT;
+}
+function recordSpanError(state, span, error) {
+  span.setStatus({ code: state.SpanStatusCode.ERROR, message: errorMessage(error) });
+  span.recordException(toError(error));
+}
+export function runWithSpan(state, span, body, onSuccess) {
+  try {
+    const result = body();
+    span.setStatus({ code: state.SpanStatusCode.OK });
+    onSuccess?.(result);
+    return result;
+  } catch (error) {
+    recordSpanError(state, span, error);
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+export async function runAsyncWithSpan(state, span, body, onSuccess) {
+  try {
+    const result = await body();
+    span.setStatus({ code: state.SpanStatusCode.OK });
+    onSuccess?.(result);
+    return result;
+  } catch (error) {
+    recordSpanError(state, span, error);
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+export function* runGeneratorWithSpan(state, span, body, onSuccess) {
+  try {
+    const result = yield* body();
+    span.setStatus({ code: state.SpanStatusCode.OK });
+    onSuccess?.(result);
+    return result;
+  } catch (error) {
+    recordSpanError(state, span, error);
+    throw error;
+  } finally {
+    span.end();
+  }
+}

package/dist/observability/types.d.ts

@@ -0,0 +1,92 @@
+import type { ActivityInterception, ChildWorkflowInterception, SignalInterception, SignalReceivedInterception, SleepInterception, WorkflowStartInterception } from '../core/interceptor';
+import type { MetricsCollector as MetricsCollectorClass } from './metrics';
+import type { OpenTelemetryApi, OpenTelemetrySpan, OpenTelemetryTracer } from './no-op-telemetry';
+/**
+ * Union of all interception context types the attributeExtractor receives.
+ *
+ * @example
+ * ```ts
+ * import { createObservabilityInterceptors, type InterceptionContext } from '@lostgradient/weft';
+ *
+ * const { interceptor } = createObservabilityInterceptors({
+ *   attributeExtractor: (ctx: InterceptionContext) => {
+ *     if ('workflowId' in ctx) return { workflowId: ctx.workflowId };
+ *     return {};
+ *   },
+ * });
+ * void interceptor;
+ * ```
+ */
+export type InterceptionContext = WorkflowStartInterception | ActivityInterception | SleepInterception | SignalInterception | ChildWorkflowInterception | SignalReceivedInterception;
+/**
+ * Configuration for {@link createObservabilityInterceptors}, which produces
+ * a unified interceptor that propagates W3C trace context and emits
+ * OpenTelemetry spans.
+ *
+ * All fields are optional. Omit `openTelemetryApi` in production — it is auto-detected
+ * from `@opentelemetry/api` when installed, and all operations fall back to
+ * no-ops when it is absent. Pass your `Engine` instance as `eventTarget` so
+ * root workflow spans are closed correctly on terminal lifecycle events.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage, createObservabilityInterceptors, type ObservabilityOptions } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * await using engine = new Engine({ storage });
+ *
+ * const options: ObservabilityOptions = {
+ *   tracerName: 'my-service',
+ *   recordPayloads: false,
+ *   eventTarget: engine,
+ * };
+ * const { interceptor } = createObservabilityInterceptors(options);
+ * void interceptor;
+ * ```
+ */
+export type ObservabilityOptions = {
+    /** Name passed to `trace.getTracer()`. Default: `'weft'`. */
+    tracerName?: string;
+    /** Version passed to `trace.getTracer()`. */
+    tracerVersion?: string;
+    /** Whether to record activity/workflow inputs as span attributes. Default: false. */
+    recordPayloads?: boolean;
+    /** Maximum serialized payload size in bytes before truncation. Default: 1024. */
+    maxPayloadSize?: number;
+    /**
+     * Extract custom span attributes from each interception context.
+     * Receives the actual interception object—not a synthetic wrapper.
+     */
+    attributeExtractor?: (interception: InterceptionContext) => Record<string, string | number | boolean>;
+    /** Metrics collector for recording counters, histograms, and gauges. */
+    metrics?: MetricsCollectorClass;
+    /**
+     * Override the OpenTelemetry API instance used by the interceptors.
+     * Primarily for testing—production code should omit this so `getOpenTelemetryApi()`
+     * auto-detects whether `@opentelemetry/api` is installed.
+     */
+    openTelemetryApi?: OpenTelemetryApi;
+    /**
+     * Event target that the engine dispatches lifecycle events on.
+     *
+     * When provided, root workflow spans are closed on terminal lifecycle events,
+     * and agent child spans are created from agent turn/tool events.
+     */
+    eventTarget?: EventTarget;
+};
+export type WorkflowSpanEntry = {
+    span: OpenTelemetrySpan;
+    createdAt: number;
+};
+export type ObservabilityState = {
+    readonly api: OpenTelemetryApi;
+    readonly trace: OpenTelemetryApi['trace'];
+    readonly SpanStatusCode: OpenTelemetryApi['SpanStatusCode'];
+    readonly tracer: OpenTelemetryTracer;
+    readonly recordPayloads: boolean;
+    readonly maxPayloadSize: number;
+    readonly attributeExtractor: ObservabilityOptions['attributeExtractor'] | undefined;
+    readonly eventTarget: EventTarget | undefined;
+    readonly metrics: MetricsCollectorClass;
+    readonly workflowSpans: Map<string, WorkflowSpanEntry>;
+};

package/dist/observability/workflow-interceptor.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowInterceptor } from '../core/interceptor';
+import type { ObservabilityState } from './types';
+export declare function buildWorkflowInterceptor(state: ObservabilityState): WorkflowInterceptor;

package/dist/observability/workflow-interceptor.js

@@ -0,0 +1,106 @@
+import { extractTraceParent } from "./propagation.js";
+import {
+  applyCustomAttributes,
+  injectSpanContext,
+  parentContextForWorkflow,
+  runAsyncWithSpan,
+  runGeneratorWithSpan,
+  runWithSpan,
+  serializePayload
+} from "./span-helpers.js";
+import { endAndRemoveWorkflowSpan, evictStaleWorkflowSpans } from "./workflow-lifecycle.js";
+export function buildWorkflowInterceptor(state) {
+  return {
+    workflowStart(interception, next) {
+      evictStaleWorkflowSpans(state);
+      const existingEntry = state.workflowSpans.get(interception.workflowId);
+      if (existingEntry) {
+        existingEntry.span.setStatus({ code: state.SpanStatusCode.OK });
+        endAndRemoveWorkflowSpan(state, interception.workflowId);
+      }
+      const span = state.tracer.startSpan(`workflow:${interception.workflowType}`, {
+        attributes: {
+          "weft.workflow.id": interception.workflowId,
+          "weft.workflow.type": interception.workflowType
+        }
+      });
+      state.workflowSpans.set(interception.workflowId, { span, createdAt: Date.now() });
+      injectSpanContext(span, interception.headers);
+      if (state.recordPayloads && interception.input !== void 0)
+        span.setAttribute("weft.payload.input", serializePayload(interception.input, state.maxPayloadSize));
+      applyCustomAttributes(state, span, interception);
+      state.metrics.increment("weft.workflow.started");
+      state.metrics.increment("weft.dpmo.operations");
+      next(interception);
+    },
+    *activity(interception, next) {
+      const span = state.tracer.startSpan(`activity:${interception.activityName}`, {
+        attributes: {
+          "weft.activity.name": interception.activityName,
+          "weft.activity.attempt": interception.attempt
+        }
+      }, parentContextForWorkflow(state, interception.workflowId));
+      injectSpanContext(span, interception.headers);
+      if (state.recordPayloads && interception.input !== void 0)
+        span.setAttribute("weft.payload.input", serializePayload(interception.input, state.maxPayloadSize));
+      applyCustomAttributes(state, span, interception);
+      const startTime = Date.now();
+      return yield* runGeneratorWithSpan(state, span, () => next(interception), () => {
+        state.metrics.record("weft.activity.duration", Date.now() - startTime);
+        state.metrics.increment("weft.activity.attempts");
+      });
+    },
+    *sleep(interception, next) {
+      const span = state.tracer.startSpan("sleep", {
+        attributes: {
+          "weft.sleep.duration": interception.duration
+        }
+      }, parentContextForWorkflow(state, interception.workflowId));
+      applyCustomAttributes(state, span, interception);
+      yield* runGeneratorWithSpan(state, span, () => next(interception));
+    },
+    *waitForSignal(interception, next) {
+      const span = state.tracer.startSpan("waitForSignal", {
+        attributes: {
+          "weft.signal.name": interception.signalName
+        }
+      }, parentContextForWorkflow(state, interception.workflowId));
+      applyCustomAttributes(state, span, interception);
+      return yield* runGeneratorWithSpan(state, span, () => next(interception));
+    },
+    async childWorkflow(interception, next) {
+      const links = [], parentTrace = extractTraceParent(interception.parentHeaders);
+      if (parentTrace)
+        links.push({
+          context: {
+            traceId: parentTrace.traceId,
+            spanId: parentTrace.spanId,
+            traceFlags: parentTrace.traceFlags
+          }
+        });
+      const span = state.tracer.startSpan(`childWorkflow:${interception.workflowType}`, {
+        attributes: {
+          "weft.child_workflow.type": interception.workflowType,
+          "weft.child_workflow.id": interception.childWorkflowId,
+          "weft.child_workflow.parent_id": interception.workflowId
+        },
+        links
+      }, state.api.context.ROOT_CONTEXT);
+      injectSpanContext(span, interception.headers);
+      if (state.recordPayloads && interception.input !== void 0)
+        span.setAttribute("weft.payload.input", serializePayload(interception.input, state.maxPayloadSize));
+      state.metrics.increment("weft.child_workflow.started");
+      return runAsyncWithSpan(state, span, () => next(interception));
+    },
+    signalReceived(interception, next) {
+      const span = state.tracer.startSpan(`signal:received:${interception.signalName}`, {
+        attributes: {
+          "weft.signal.name": interception.signalName,
+          "weft.signal.workflow_id": interception.workflowId
+        }
+      });
+      applyCustomAttributes(state, span, interception);
+      runWithSpan(state, span, () => next(interception));
+    }
+  };
+}

package/dist/observability/workflow-lifecycle.d.ts

@@ -0,0 +1,8 @@
+import type { ObservabilityState } from './types';
+export declare function evictStaleWorkflowSpans(state: ObservabilityState): void;
+export declare function endAndRemoveWorkflowSpan(state: ObservabilityState, workflowId: string): void;
+export declare function createWorkflowLifecycle(state: ObservabilityState): {
+    endWorkflowSpan: (workflowId: string, status: 'ok' | 'error', message?: string) => void;
+    evictStaleSpans: (maxAgeMs?: number) => number;
+    dispose: () => void;
+};

package/dist/observability/workflow-lifecycle.js

@@ -0,0 +1,103 @@
+import {
+  WorkflowCancelledEvent,
+  WorkflowCompletedEvent,
+  WorkflowFailedEvent,
+  WorkflowTimedOutEvent
+} from "../core/events.js";
+const WORKFLOW_SPAN_TTL_MS = 3600000, WORKFLOW_SPAN_MAX_SIZE = 1e4, DEFAULT_STALE_SPAN_MAX_AGE_MS = 3600000;
+export function evictStaleWorkflowSpans(state) {
+  const now = Date.now();
+  for (const [id, entry] of state.workflowSpans)
+    if (now - entry.createdAt > WORKFLOW_SPAN_TTL_MS) {
+      entry.span.end();
+      state.workflowSpans.delete(id);
+    }
+  if (state.workflowSpans.size > WORKFLOW_SPAN_MAX_SIZE) {
+    const excess = state.workflowSpans.size - WORKFLOW_SPAN_MAX_SIZE;
+    let removed = 0;
+    for (const [id, entry] of state.workflowSpans) {
+      if (removed >= excess)
+        break;
+      entry.span.end();
+      state.workflowSpans.delete(id);
+      removed++;
+    }
+  }
+}
+export function endAndRemoveWorkflowSpan(state, workflowId) {
+  const entry = state.workflowSpans.get(workflowId);
+  if (entry) {
+    entry.span.end();
+    state.workflowSpans.delete(workflowId);
+  }
+}
+export function createWorkflowLifecycle(state) {
+  function endWorkflowSpan(workflowId, status, message) {
+    const entry = state.workflowSpans.get(workflowId);
+    if (!entry)
+      return;
+    if (status === "error")
+      entry.span.setStatus({
+        code: state.SpanStatusCode.ERROR,
+        ...message ? { message } : {}
+      });
+    else
+      entry.span.setStatus({ code: state.SpanStatusCode.OK });
+    entry.span.end();
+    state.workflowSpans.delete(workflowId);
+  }
+  const onWorkflowCompleted = (event) => {
+    if (!(event instanceof WorkflowCompletedEvent))
+      return;
+    endWorkflowSpan(event.workflowId, "ok");
+  }, onWorkflowFailed = (event) => {
+    if (!(event instanceof WorkflowFailedEvent))
+      return;
+    endWorkflowSpan(event.workflowId, "error", event.error.message);
+    state.metrics.increment("weft.dpmo.defects");
+  }, onWorkflowCancelled = (event) => {
+    if (!(event instanceof WorkflowCancelledEvent))
+      return;
+    endWorkflowSpan(event.workflowId, "error", "Workflow cancelled");
+  }, onWorkflowTimedOut = (event) => {
+    if (!(event instanceof WorkflowTimedOutEvent))
+      return;
+    endWorkflowSpan(event.workflowId, "error", `Workflow timed out (${event.timeoutType}) after ${event.elapsed}ms`);
+    state.metrics.increment("weft.dpmo.defects");
+  };
+  if (state.eventTarget) {
+    state.eventTarget.addEventListener(WorkflowCompletedEvent.type, onWorkflowCompleted);
+    state.eventTarget.addEventListener(WorkflowFailedEvent.type, onWorkflowFailed);
+    state.eventTarget.addEventListener(WorkflowCancelledEvent.type, onWorkflowCancelled);
+    state.eventTarget.addEventListener(WorkflowTimedOutEvent.type, onWorkflowTimedOut);
+  }
+  function evictStaleSpans(maxAgeMs = DEFAULT_STALE_SPAN_MAX_AGE_MS) {
+    const cutoff = Date.now() - maxAgeMs;
+    let evicted = 0;
+    for (const [workflowId, entry] of state.workflowSpans)
+      if (entry.createdAt <= cutoff) {
+        entry.span.setStatus({
+          code: state.SpanStatusCode.ERROR,
+          message: "span evicted (stale)"
+        });
+        entry.span.end();
+        state.workflowSpans.delete(workflowId);
+        evicted++;
+      }
+    return evicted;
+  }
+  function dispose() {
+    if (state.eventTarget) {
+      state.eventTarget.removeEventListener(WorkflowCompletedEvent.type, onWorkflowCompleted);
+      state.eventTarget.removeEventListener(WorkflowFailedEvent.type, onWorkflowFailed);
+      state.eventTarget.removeEventListener(WorkflowCancelledEvent.type, onWorkflowCancelled);
+      state.eventTarget.removeEventListener(WorkflowTimedOutEvent.type, onWorkflowTimedOut);
+    }
+    for (const entry of state.workflowSpans.values()) {
+      entry.span.setStatus({ code: state.SpanStatusCode.ERROR, message: "Observability disposed" });
+      entry.span.end();
+    }
+    state.workflowSpans.clear();
+  }
+  return { endWorkflowSpan, evictStaleSpans, dispose };
+}