autotel 4.2.5 → 5.0.0

package/dist/workflow.js

@@ -1,6 +1,7 @@
 import { getActiveSpan } from "./trace-helpers.js";
-import { a as trace } from "./functional-CrAq8Az8.js";
+import { c as withTracing } from "./functional-Bit6noRu.js";
 import { t as emitCorrelatedEvent } from "./correlated-events-Bzh5y-UB.js";
+import { t as assertTraceFactory } from "./trace-factory-validation-BjVAinz6.js";
 import * as nodeAsyncHooks from "node:async_hooks";
 
 //#region src/workflow.ts
@@ -95,9 +96,13 @@ const workflowContextStorage = new nodeAsyncHooks.AsyncLocalStorage();
 * ```
 */
 function traceWorkflow(config) {
+	if (!config || typeof config !== "object") throw new TypeError("traceWorkflow: config must be an object");
+	if (typeof config.name !== "string" || config.name.trim() === "") throw new TypeError("traceWorkflow: config.name must be a non-empty string");
+	if (typeof config.workflowId !== "string" && typeof config.workflowId !== "function") throw new TypeError("traceWorkflow: config.workflowId must be a string or function");
 	const spanName = `workflow.${config.name}`;
 	return (fnFactory) => {
-		return trace(spanName, (baseCtx) => {
+		assertTraceFactory("traceWorkflow", fnFactory);
+		return withTracing({ name: spanName })((baseCtx) => {
 			return async (...args) => {
 				const workflowId = typeof config.workflowId === "function" ? config.workflowId(...args) : config.workflowId;
 				const ctx = createWorkflowContext(baseCtx, config.name, workflowId);
@@ -110,7 +115,9 @@ function traceWorkflow(config) {
 				}
 				return workflowContextStorage.run(ctx, async () => {
 					try {
-						const result = await fnFactory(ctx)(...args);
+						const userFn = fnFactory(ctx);
+						assertTraceFactory("traceWorkflow", userFn, "result");
+						const result = await userFn(...args);
 						ctx.setWorkflowStatus("completed");
 						config.onComplete?.(ctx, result);
 						return result;
@@ -136,31 +143,12 @@ function traceWorkflow(config) {
 		});
 	};
 }
-/**
-* Create a traced workflow step
-*
-* Wraps step logic with automatic linking to previous steps,
-* compensation registration, and status tracking.
-*
-* @param config - Step configuration
-* @returns Factory function that wraps your step logic
-*
-* @example Step with compensation
-* ```typescript
-* const chargePayment = traceStep({
-*   name: 'ChargePayment',
-*   linkToPrevious: true,
-*   compensate: async (error) => {
-*     await paymentService.refund(paymentId);
-*   },
-* })(async (amount: number) => {
-*   return await paymentService.charge(amount);
-* });
-* ```
-*/
 function traceStep(config) {
-	return (fn) => {
-		return trace(`step.${config.name}`, (baseCtx) => {
+	if (!config || typeof config !== "object") throw new TypeError("traceStep: config must be an object");
+	if (typeof config.name !== "string" || config.name.trim() === "") throw new TypeError("traceStep: config.name must be a non-empty string");
+	return ((handler) => {
+		if (typeof handler !== "function") throw new TypeError("traceStep(config)(handler): handler must be a function");
+		return withTracing({ name: `step.${config.name}` })((baseCtx) => {
 			return async (...args) => {
 				const workflowCtx = workflowContextStorage.getStore() ?? null;
 				const ctx = createStepContext(baseCtx, config, workflowCtx);
@@ -173,7 +161,13 @@ function traceStep(config) {
 					for (const [key, value] of Object.entries(config.attributes)) if (value !== void 0) ctx.setAttribute(key, value);
 				}
 				await addStepLinks(ctx, config, workflowCtx);
-				if (config.compensate && workflowCtx) workflowCtx.registerCompensation(config.name, config.compensate);
+				if (config.compensate && workflowCtx) {
+					const compensate = config.compensate;
+					workflowCtx.registerCompensation(config.name, (error) => {
+						if (compensate.length >= 2) return compensate(ctx, error);
+						return compensate(error);
+					});
+				}
 				let lastError;
 				const maxAttempts = config.retry?.maxAttempts ?? 1;
 				for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
@@ -185,7 +179,7 @@ function traceStep(config) {
 						});
 						if (config.retry?.backoffMs) await sleep(config.retry.backoffMs * attempt);
 					}
-					const result = await fn(...args);
+					const result = await handler(...args);
 					ctx.setAttribute("workflow.step.status", "completed");
 					ctx.complete();
 					config.onComplete?.(ctx);
@@ -203,7 +197,7 @@ function traceStep(config) {
 				throw lastError;
 			};
 		});
-	};
+	});
 }
 /**
 * Create workflow-extended context

package/dist/workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.js","names":[],"sources":["../src/workflow.ts"],"sourcesContent":["/**\n * Workflow and Saga tracing helpers\n *\n * Provides specialized tracing for multi-step workflows and sagas with\n * automatic step linking, compensation tracking, and workflow correlation.\n *\n * @example Simple workflow\n * ```typescript\n * import { traceWorkflow, traceStep } from 'autotel/workflow';\n *\n * export const processOrder = traceWorkflow({\n *   name: 'OrderFulfillment',\n *   workflowId: (order) => order.id,\n * })(ctx => async (order: Order) => {\n *   await validateOrder(order);\n *   await chargePayment(order);\n *   await shipOrder(order);\n * });\n * ```\n *\n * @example Saga with compensation\n * ```typescript\n * import { traceWorkflow, traceStep } from 'autotel/workflow';\n *\n * export const orderSaga = traceWorkflow({\n *   name: 'OrderSaga',\n *   workflowId: () => generateUUID(),\n * })(ctx => async (order: Order) => {\n *\n *   const reserveStep = traceStep({\n *     name: 'ReserveInventory',\n *     compensate: async () => {\n *       await releaseInventory(order.items);\n *     },\n *   })(async () => {\n *     await inventoryService.reserve(order.items);\n *   });\n *   await reserveStep();\n *\n *   const paymentStep = traceStep({\n *     name: 'ProcessPayment',\n *     linkToPrevious: true,\n *     compensate: async () => {\n *       await refundPayment(order.paymentId);\n *     },\n *   })(async () => {\n *     await paymentService.charge(order);\n *   });\n *   await paymentStep();\n * });\n * ```\n *\n * @module\n */\n\n// namespace import for browser-bundler compat — see node-require.ts\nimport * as nodeAsyncHooks from 'node:async_hooks';\nimport type { Attributes, Link, SpanContext } from '@opentelemetry/api';\nimport { emitCorrelatedEvent } from './correlated-events';\nimport { trace } from './functional';\nimport type { TraceContext } from './trace-context';\nimport { getActiveSpan } from './trace-helpers';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Workflow status\n */\nexport type WorkflowStatus =\n  | 'pending'\n  | 'running'\n  | 'completed'\n  | 'failed'\n  | 'compensating'\n  | 'compensated'\n  | 'compensation_failed';\n\n/**\n * Step status\n */\nexport type StepStatus =\n  | 'pending'\n  | 'running'\n  | 'completed'\n  | 'failed'\n  | 'skipped'\n  | 'compensated';\n\n/**\n * Configuration for workflow tracing\n */\nexport interface WorkflowConfig<TArgs extends unknown[] = unknown[]> {\n  /** Workflow name (e.g., 'OrderFulfillment', 'UserOnboarding') */\n  name: string;\n\n  /**\n   * Function to extract or generate workflow ID\n   * Can be static string, function of args, or generator\n   */\n  workflowId: string | ((...args: TArgs) => string);\n\n  /** Optional workflow version */\n  version?: string;\n\n  /** Additional attributes */\n  attributes?: Attributes;\n\n  /** Callback on workflow completion */\n  onComplete?: (ctx: WorkflowContext, result: unknown) => void;\n\n  /** Callback on workflow failure */\n  onFailed?: (ctx: WorkflowContext, error: Error) => void;\n\n  /** Callback on compensation start */\n  onCompensating?: (ctx: WorkflowContext) => void;\n}\n\n/**\n * Configuration for workflow step tracing\n */\nexport interface StepConfig {\n  /** Step name */\n  name: string;\n\n  /** Optional step description */\n  description?: string;\n\n  /** Step index (auto-assigned if not provided) */\n  index?: number;\n\n  /** Link to previous step span */\n  linkToPrevious?: boolean;\n\n  /** Link to specific step(s) by name */\n  linkTo?: string | string[];\n\n  /** Additional attributes */\n  attributes?: Attributes;\n\n  /** Compensation handler for saga rollback */\n  compensate?: (error: Error) => Promise<void> | void;\n\n  /** Whether this step is idempotent */\n  idempotent?: boolean;\n\n  /** Retry configuration */\n  retry?: {\n    maxAttempts: number;\n    backoffMs?: number;\n  };\n\n  /** Callback on step completion */\n  onComplete?: (ctx: StepContext) => void;\n\n  /** Callback on step failure */\n  onFailed?: (ctx: StepContext, error: Error) => void;\n}\n\n/**\n * Step metadata stored for linking and compensation\n */\ninterface StepMetadata {\n  name: string;\n  index: number;\n  status: StepStatus;\n  spanContext?: SpanContext;\n  compensate?: (error: Error) => Promise<void> | void;\n  startTime: number;\n  endTime?: number;\n}\n\n/**\n * Extended trace context for workflows\n */\nexport interface WorkflowContext extends TraceContext {\n  /** Get the workflow ID */\n  getWorkflowId(): string;\n\n  /** Get workflow name */\n  getWorkflowName(): string;\n\n  /** Get current workflow status */\n  getStatus(): WorkflowStatus;\n\n  /** Mark step as completed and store for linking */\n  completeStep(stepName: string): void;\n\n  /** Get previous step's span context for linking */\n  getPreviousStep(stepName?: string): SpanContext | null;\n\n  /** Get all completed steps */\n  getCompletedSteps(): string[];\n\n  /** Register a compensation handler */\n  registerCompensation(\n    stepName: string,\n    handler: (error: Error) => Promise<void> | void,\n  ): void;\n\n  /** Trigger compensation for all registered steps */\n  compensate(error: Error): Promise<void>;\n\n  /** Record compensation result */\n  recordCompensation(stepName: string, success: boolean, error?: Error): void;\n\n  /** Set workflow status */\n  setWorkflowStatus(status: WorkflowStatus): void;\n}\n\n/**\n * Extended trace context for workflow steps\n */\nexport interface StepContext extends TraceContext {\n  /** Get step name */\n  getStepName(): string;\n\n  /** Get step index */\n  getStepIndex(): number;\n\n  /** Mark this step as completed */\n  complete(): void;\n\n  /** Skip this step */\n  skip(reason?: string): void;\n\n  /** Get workflow context */\n  getWorkflowContext(): WorkflowContext | null;\n}\n\n// ============================================================================\n// Storage\n// ============================================================================\n\n// Store workflow state in a WeakMap keyed by span\nconst workflowStates = new WeakMap<\n  object,\n  {\n    workflowId: string;\n    workflowName: string;\n    status: WorkflowStatus;\n    steps: Map<string, StepMetadata>;\n    stepCounter: number;\n    compensations: Map<string, (error: Error) => Promise<void> | void>;\n  }\n>();\n\n/**\n * AsyncLocalStorage for workflow context (async-safe)\n *\n * This replaces the previous module-level variable which was NOT safe for\n * concurrent workflows. AsyncLocalStorage ensures each async execution chain\n * has its own isolated workflow context.\n */\nconst workflowContextStorage =\n  new nodeAsyncHooks.AsyncLocalStorage<WorkflowContext>();\n\n// ============================================================================\n// Workflow Helper\n// ============================================================================\n\n/**\n * Create a traced workflow function\n *\n * Wraps business logic in a workflow span with automatic step tracking,\n * correlation via workflow ID, and compensation support.\n *\n * @param config - Workflow configuration\n * @returns Factory function that wraps your workflow logic\n *\n * @example Order fulfillment workflow\n * ```typescript\n * export const fulfillOrder = traceWorkflow({\n *   name: 'OrderFulfillment',\n *   workflowId: (order) => order.id,\n *   version: '2.0',\n * })(ctx => async (order: Order) => {\n *   ctx.setAttribute('order.total', order.total);\n *\n *   await validateOrder(order);\n *   await processPayment(order);\n *   await fulfillItems(order);\n *   await notifyCustomer(order);\n *\n *   return { success: true, orderId: order.id };\n * });\n * ```\n */\nexport function traceWorkflow<TArgs extends unknown[], TReturn>(\n  config: WorkflowConfig<TArgs>,\n) {\n  const spanName = `workflow.${config.name}`;\n\n  return (\n    fnFactory: (ctx: WorkflowContext) => (...args: TArgs) => Promise<TReturn>,\n  ): ((...args: TArgs) => Promise<TReturn>) => {\n    return trace<TArgs, TReturn>(spanName, (baseCtx) => {\n      return async (...args: TArgs) => {\n        // Generate or extract workflow ID\n        const workflowId =\n          typeof config.workflowId === 'function'\n            ? config.workflowId(...args)\n            : config.workflowId;\n\n        // Create workflow context\n        const ctx = createWorkflowContext(baseCtx, config.name, workflowId);\n\n        // Set workflow attributes\n        ctx.setAttribute('workflow.name', config.name);\n        ctx.setAttribute('workflow.id', workflowId);\n        if (config.version) {\n          ctx.setAttribute('workflow.version', config.version);\n        }\n        ctx.setAttribute('workflow.status', 'running');\n\n        // Set custom attributes\n        if (config.attributes) {\n          for (const [key, value] of Object.entries(config.attributes)) {\n            if (value !== undefined) {\n              ctx.setAttribute(key, value as string | number | boolean);\n            }\n          }\n        }\n\n        // Run workflow in AsyncLocalStorage context for async-safety\n        // This ensures concurrent workflows have isolated contexts\n        return workflowContextStorage.run(ctx, async () => {\n          try {\n            // Execute workflow\n            const userFn = fnFactory(ctx);\n            const result = await userFn(...args);\n\n            // Mark as completed\n            ctx.setWorkflowStatus('completed');\n            config.onComplete?.(ctx, result);\n\n            return result;\n          } catch (error) {\n            // Mark as failed\n            ctx.setWorkflowStatus('failed');\n            config.onFailed?.(ctx, error as Error);\n\n            // Check if we have compensations to run\n            const state = getWorkflowState();\n            if (state && state.compensations.size > 0) {\n              ctx.setWorkflowStatus('compensating');\n              config.onCompensating?.(ctx);\n\n              try {\n                await ctx.compensate(error as Error);\n                ctx.setWorkflowStatus('compensated');\n              } catch (compensationError) {\n                ctx.setWorkflowStatus('compensation_failed');\n                ctx.setAttribute(\n                  'workflow.compensation.error',\n                  String(compensationError),\n                );\n              }\n            }\n\n            throw error;\n          }\n        });\n      };\n    });\n  };\n}\n\n/**\n * Create a traced workflow step\n *\n * Wraps step logic with automatic linking to previous steps,\n * compensation registration, and status tracking.\n *\n * @param config - Step configuration\n * @returns Factory function that wraps your step logic\n *\n * @example Step with compensation\n * ```typescript\n * const chargePayment = traceStep({\n *   name: 'ChargePayment',\n *   linkToPrevious: true,\n *   compensate: async (error) => {\n *     await paymentService.refund(paymentId);\n *   },\n * })(async (amount: number) => {\n *   return await paymentService.charge(amount);\n * });\n * ```\n */\nexport function traceStep<TArgs extends unknown[], TReturn>(\n  config: StepConfig,\n) {\n  return (\n    fn: (...args: TArgs) => Promise<TReturn>,\n  ): ((...args: TArgs) => Promise<TReturn>) => {\n    const spanName = `step.${config.name}`;\n\n    return trace<TArgs, TReturn>(spanName, (baseCtx) => {\n      return async (...args: TArgs) => {\n        // Get workflow context from AsyncLocalStorage (async-safe)\n        const workflowCtx = workflowContextStorage.getStore() ?? null;\n\n        // Create step context\n        const ctx = createStepContext(baseCtx, config, workflowCtx);\n\n        // Set step attributes\n        ctx.setAttribute('workflow.step.name', config.name);\n        ctx.setAttribute('workflow.step.index', ctx.getStepIndex());\n        ctx.setAttribute('workflow.step.status', 'running');\n\n        if (config.description) {\n          ctx.setAttribute('workflow.step.description', config.description);\n        }\n\n        if (config.idempotent) {\n          ctx.setAttribute('workflow.step.idempotent', true);\n        }\n\n        // Set custom attributes\n        if (config.attributes) {\n          for (const [key, value] of Object.entries(config.attributes)) {\n            if (value !== undefined) {\n              ctx.setAttribute(key, value as string | number | boolean);\n            }\n          }\n        }\n\n        // Link to previous steps\n        await addStepLinks(ctx, config, workflowCtx);\n\n        // Register compensation if provided\n        if (config.compensate && workflowCtx) {\n          workflowCtx.registerCompensation(config.name, config.compensate);\n        }\n\n        // Execute with optional retry\n        let lastError: Error | undefined;\n        const maxAttempts = config.retry?.maxAttempts ?? 1;\n\n        for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n          try {\n            if (attempt > 1) {\n              ctx.setAttribute('workflow.step.retry_attempt', attempt);\n              emitCorrelatedEvent(ctx, 'step_retry', {\n                'workflow.step.attempt': attempt,\n                'workflow.step.max_attempts': maxAttempts,\n              });\n\n              // Backoff\n              if (config.retry?.backoffMs) {\n                await sleep(config.retry.backoffMs * attempt);\n              }\n            }\n\n            const result = await fn(...args);\n\n            // Mark as completed\n            ctx.setAttribute('workflow.step.status', 'completed');\n            ctx.complete();\n            config.onComplete?.(ctx);\n\n            return result;\n          } catch (error) {\n            lastError = error as Error;\n\n            if (attempt < maxAttempts) {\n              emitCorrelatedEvent(ctx, 'step_retry_scheduled', {\n                'workflow.step.error': String(error),\n                'workflow.step.attempt': attempt,\n              });\n            }\n          }\n        }\n\n        // All attempts failed\n        ctx.setAttribute('workflow.step.status', 'failed');\n        ctx.setAttribute('workflow.step.error', String(lastError));\n        config.onFailed?.(ctx, lastError!);\n\n        throw lastError;\n      };\n    });\n  };\n}\n\n// ============================================================================\n// Context Creation\n// ============================================================================\n\n/**\n * Create workflow-extended context\n */\nfunction createWorkflowContext(\n  baseCtx: TraceContext,\n  workflowName: string,\n  workflowId: string,\n): WorkflowContext {\n  // Initialize state\n  const span = getActiveSpan();\n  const state = {\n    workflowId,\n    workflowName,\n    status: 'running' as WorkflowStatus,\n    steps: new Map<string, StepMetadata>(),\n    stepCounter: 0,\n    compensations: new Map<string, (error: Error) => Promise<void> | void>(),\n  };\n\n  if (span) {\n    workflowStates.set(span, state);\n  }\n\n  return {\n    ...baseCtx,\n\n    getWorkflowId(): string {\n      return workflowId;\n    },\n\n    getWorkflowName(): string {\n      return workflowName;\n    },\n\n    getStatus(): WorkflowStatus {\n      return state.status;\n    },\n\n    completeStep(stepName: string): void {\n      let step = state.steps.get(stepName);\n      if (!step) {\n        // Auto-create step entry for manually managed steps\n        // (when using registerCompensation without traceStep)\n        step = {\n          name: stepName,\n          index: state.stepCounter++,\n          status: 'pending',\n          startTime: Date.now(),\n        };\n        state.steps.set(stepName, step);\n      }\n      step.status = 'completed';\n      step.endTime = Date.now();\n\n      // Capture span context for linking\n      const currentSpan = getActiveSpan();\n      if (currentSpan) {\n        step.spanContext = currentSpan.spanContext();\n      }\n    },\n\n    getPreviousStep(stepName?: string): SpanContext | null {\n      if (stepName) {\n        const step = state.steps.get(stepName);\n        return step?.spanContext ?? null;\n      }\n\n      // Get last completed step\n      let lastStep: StepMetadata | null = null;\n      for (const step of state.steps.values()) {\n        if (\n          step.status === 'completed' &&\n          (!lastStep || step.index > lastStep.index)\n        ) {\n          lastStep = step;\n        }\n      }\n\n      return lastStep?.spanContext ?? null;\n    },\n\n    getCompletedSteps(): string[] {\n      const completed: string[] = [];\n      for (const [name, step] of state.steps) {\n        if (step.status === 'completed') {\n          completed.push(name);\n        }\n      }\n      return completed.toSorted(\n        (a, b) =>\n          (state.steps.get(a)?.index ?? 0) - (state.steps.get(b)?.index ?? 0),\n      );\n    },\n\n    registerCompensation(\n      stepName: string,\n      handler: (error: Error) => Promise<void> | void,\n    ): void {\n      state.compensations.set(stepName, handler);\n    },\n\n    async compensate(error: Error): Promise<void> {\n      // Execute compensations in reverse order\n      const compensationOrder = [...state.compensations.entries()].toReversed();\n\n      for (const [stepName, handler] of compensationOrder) {\n        const step = state.steps.get(stepName);\n        if (step && step.status === 'completed') {\n          try {\n            emitCorrelatedEvent(baseCtx, 'compensation_started', {\n              'workflow.step.name': stepName,\n            });\n\n            await Promise.resolve(handler(error));\n\n            this.recordCompensation(stepName, true);\n            step.status = 'compensated';\n          } catch (compensationError) {\n            this.recordCompensation(\n              stepName,\n              false,\n              compensationError as Error,\n            );\n            throw compensationError;\n          }\n        }\n      }\n    },\n\n    recordCompensation(\n      stepName: string,\n      success: boolean,\n      error?: Error,\n    ): void {\n      emitCorrelatedEvent(baseCtx, 'compensation_completed', {\n        'workflow.step.name': stepName,\n        'workflow.compensation.success': success,\n        ...(error && { 'workflow.compensation.error': String(error) }),\n      });\n\n      baseCtx.setAttribute(\n        `workflow.compensation.${stepName}`,\n        success ? 'success' : 'failed',\n      );\n    },\n\n    setWorkflowStatus(status: WorkflowStatus): void {\n      state.status = status;\n      baseCtx.setAttribute('workflow.status', status);\n\n      emitCorrelatedEvent(baseCtx, 'workflow_status_changed', {\n        'workflow.status': status,\n      });\n    },\n  };\n}\n\n/**\n * Create step-extended context\n */\nfunction createStepContext(\n  baseCtx: TraceContext,\n  config: StepConfig,\n  workflowCtx: WorkflowContext | null,\n): StepContext {\n  // Determine step index\n  let stepIndex = config.index ?? 0;\n  if (workflowCtx) {\n    const span = getActiveSpan();\n    if (span) {\n      const state = workflowStates.get(span);\n      if (state) {\n        stepIndex = config.index ?? state.stepCounter++;\n      }\n    }\n  }\n\n  // Register step metadata\n  if (workflowCtx) {\n    const wfSpan = getActiveSpan();\n    if (wfSpan) {\n      const state = workflowStates.get(wfSpan);\n      if (state) {\n        state.steps.set(config.name, {\n          name: config.name,\n          index: stepIndex,\n          status: 'running',\n          startTime: Date.now(),\n          compensate: config.compensate,\n        });\n      }\n    }\n  }\n\n  return {\n    ...baseCtx,\n\n    getStepName(): string {\n      return config.name;\n    },\n\n    getStepIndex(): number {\n      return stepIndex;\n    },\n\n    complete(): void {\n      if (workflowCtx) {\n        workflowCtx.completeStep(config.name);\n      }\n    },\n\n    skip(reason?: string): void {\n      baseCtx.setAttribute('workflow.step.status', 'skipped');\n      if (reason) {\n        baseCtx.setAttribute('workflow.step.skip_reason', reason);\n      }\n      emitCorrelatedEvent(baseCtx, 'step_skipped', {\n        'workflow.step.name': config.name,\n        ...(reason && { 'workflow.step.skip_reason': reason }),\n      });\n    },\n\n    getWorkflowContext(): WorkflowContext | null {\n      return workflowCtx;\n    },\n  };\n}\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Get workflow state from context\n */\nfunction getWorkflowState() {\n  const span = getActiveSpan();\n  return span ? workflowStates.get(span) : null;\n}\n\n/**\n * Add links to previous steps\n */\nasync function addStepLinks(\n  ctx: StepContext,\n  config: StepConfig,\n  workflowCtx: WorkflowContext | null,\n): Promise<void> {\n  if (!workflowCtx) return;\n\n  const links: Link[] = [];\n\n  // Link to previous step\n  if (config.linkToPrevious) {\n    const prevSpanContext = workflowCtx.getPreviousStep();\n    if (prevSpanContext) {\n      links.push({\n        context: prevSpanContext,\n        attributes: {\n          'workflow.link.type': 'sequence',\n        },\n      });\n    }\n  }\n\n  // Link to specific steps\n  if (config.linkTo) {\n    const stepNames = Array.isArray(config.linkTo)\n      ? config.linkTo\n      : [config.linkTo];\n\n    for (const stepName of stepNames) {\n      const spanContext = workflowCtx.getPreviousStep(stepName);\n      if (spanContext) {\n        links.push({\n          context: spanContext,\n          attributes: {\n            'workflow.link.type': 'dependency',\n            'workflow.link.step': stepName,\n          },\n        });\n      }\n    }\n  }\n\n  // Add all links\n  if (links.length > 0) {\n    ctx.addLinks(links);\n  }\n}\n\n/**\n * Sleep utility for retry backoff\n */\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// ============================================================================\n// Convenience Exports\n// ============================================================================\n\n/**\n * Get current workflow context (if inside a workflow)\n *\n * Uses AsyncLocalStorage to ensure async-safety when multiple\n * workflows are running concurrently.\n */\nexport function getCurrentWorkflowContext(): WorkflowContext | null {\n  return workflowContextStorage.getStore() ?? null;\n}\n\n/**\n * Check if currently executing inside a workflow\n *\n * Uses AsyncLocalStorage to ensure async-safety when multiple\n * workflows are running concurrently.\n */\nexport function isInWorkflow(): boolean {\n  return workflowContextStorage.getStore() !== undefined;\n}\n"],"mappings":"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"}
+{"version":3,"file":"workflow.js","names":[],"sources":["../src/workflow.ts"],"sourcesContent":["/**\n * Workflow and Saga tracing helpers\n *\n * Provides specialized tracing for multi-step workflows and sagas with\n * automatic step linking, compensation tracking, and workflow correlation.\n *\n * @example Simple workflow\n * ```typescript\n * import { traceWorkflow, traceStep } from 'autotel/workflow';\n *\n * export const processOrder = traceWorkflow({\n *   name: 'OrderFulfillment',\n *   workflowId: (order) => order.id,\n * })(ctx => async (order: Order) => {\n *   await validateOrder(order);\n *   await chargePayment(order);\n *   await shipOrder(order);\n * });\n * ```\n *\n * @example Saga with compensation\n * ```typescript\n * import { traceWorkflow, traceStep } from 'autotel/workflow';\n *\n * export const orderSaga = traceWorkflow({\n *   name: 'OrderSaga',\n *   workflowId: () => generateUUID(),\n * })(ctx => async (order: Order) => {\n *\n *   const reserveStep = traceStep({\n *     name: 'ReserveInventory',\n *     compensate: async () => {\n *       await releaseInventory(order.items);\n *     },\n *   })(async () => {\n *     await inventoryService.reserve(order.items);\n *   });\n *   await reserveStep();\n *\n *   const paymentStep = traceStep({\n *     name: 'ProcessPayment',\n *     linkToPrevious: true,\n *     compensate: async () => {\n *       await refundPayment(order.paymentId);\n *     },\n *   })(async () => {\n *     await paymentService.charge(order);\n *   });\n *   await paymentStep();\n * });\n * ```\n *\n * @module\n */\n\n// namespace import for browser-bundler compat — see node-require.ts\nimport * as nodeAsyncHooks from 'node:async_hooks';\nimport type { Attributes, Link, SpanContext } from '@opentelemetry/api';\nimport { emitCorrelatedEvent } from './correlated-events';\nimport { withTracing } from './functional';\nimport { assertTraceFactory } from './trace-factory-validation';\nimport type { TraceContext } from './trace-context';\nimport { getActiveSpan } from './trace-helpers';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Workflow status\n */\nexport type WorkflowStatus =\n  | 'pending'\n  | 'running'\n  | 'completed'\n  | 'failed'\n  | 'compensating'\n  | 'compensated'\n  | 'compensation_failed';\n\n/**\n * Step status\n */\nexport type StepStatus =\n  'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'compensated';\n\n/**\n * Configuration for workflow tracing\n */\nexport interface WorkflowConfig<TArgs extends unknown[] = unknown[]> {\n  /** Workflow name (e.g., 'OrderFulfillment', 'UserOnboarding') */\n  name: string;\n\n  /**\n   * Function to extract or generate workflow ID\n   * Can be static string, function of args, or generator\n   */\n  workflowId: string | ((...args: TArgs) => string);\n\n  /** Optional workflow version */\n  version?: string;\n\n  /** Additional attributes */\n  attributes?: Attributes;\n\n  /** Callback on workflow completion */\n  onComplete?: (ctx: WorkflowContext, result: unknown) => void;\n\n  /** Callback on workflow failure */\n  onFailed?: (ctx: WorkflowContext, error: Error) => void;\n\n  /** Callback on compensation start */\n  onCompensating?: (ctx: WorkflowContext) => void;\n}\n\n/**\n * Configuration for workflow step tracing\n */\nexport interface StepConfig {\n  /** Step name */\n  name: string;\n\n  /** Optional step description */\n  description?: string;\n\n  /** Step index (auto-assigned if not provided) */\n  index?: number;\n\n  /** Link to previous step span */\n  linkToPrevious?: boolean;\n\n  /** Link to specific step(s) by name */\n  linkTo?: string | string[];\n\n  /** Additional attributes */\n  attributes?: Attributes;\n\n  /**\n   * Compensation handler for saga rollback.\n   *\n   * The two-arg `(ctx, error)` form is detected via `Function.length`, so it\n   * must not use default or rest parameters (they reduce the reported arity).\n   */\n  compensate?:\n    | ((error: Error) => Promise<void> | void)\n    | ((ctx: StepContext, error: Error) => Promise<void> | void);\n\n  /** Whether this step is idempotent */\n  idempotent?: boolean;\n\n  /** Retry configuration */\n  retry?: {\n    maxAttempts: number;\n    backoffMs?: number;\n  };\n\n  /** Callback on step completion */\n  onComplete?: (ctx: StepContext) => void;\n\n  /** Callback on step failure */\n  onFailed?: (ctx: StepContext, error: Error) => void;\n}\n\n/**\n * Step metadata stored for linking and compensation\n */\ninterface StepMetadata {\n  name: string;\n  index: number;\n  status: StepStatus;\n  spanContext?: SpanContext;\n  compensate?: StepConfig['compensate'];\n  startTime: number;\n  endTime?: number;\n}\n\n/**\n * Extended trace context for workflows\n */\nexport interface WorkflowContext extends TraceContext {\n  /** Get the workflow ID */\n  getWorkflowId(): string;\n\n  /** Get workflow name */\n  getWorkflowName(): string;\n\n  /** Get current workflow status */\n  getStatus(): WorkflowStatus;\n\n  /** Mark step as completed and store for linking */\n  completeStep(stepName: string): void;\n\n  /** Get previous step's span context for linking */\n  getPreviousStep(stepName?: string): SpanContext | null;\n\n  /** Get all completed steps */\n  getCompletedSteps(): string[];\n\n  /** Register a compensation handler */\n  registerCompensation(\n    stepName: string,\n    handler: (error: Error) => Promise<void> | void,\n  ): void;\n\n  /** Trigger compensation for all registered steps */\n  compensate(error: Error): Promise<void>;\n\n  /** Record compensation result */\n  recordCompensation(stepName: string, success: boolean, error?: Error): void;\n\n  /** Set workflow status */\n  setWorkflowStatus(status: WorkflowStatus): void;\n}\n\n/**\n * Extended trace context for workflow steps\n */\nexport interface StepContext extends TraceContext {\n  /** Get step name */\n  getStepName(): string;\n\n  /** Get step index */\n  getStepIndex(): number;\n\n  /** Mark this step as completed */\n  complete(): void;\n\n  /** Skip this step */\n  skip(reason?: string): void;\n\n  /** Get workflow context */\n  getWorkflowContext(): WorkflowContext | null;\n}\n\n// ============================================================================\n// Storage\n// ============================================================================\n\n// Store workflow state in a WeakMap keyed by span\nconst workflowStates = new WeakMap<\n  object,\n  {\n    workflowId: string;\n    workflowName: string;\n    status: WorkflowStatus;\n    steps: Map<string, StepMetadata>;\n    stepCounter: number;\n    compensations: Map<string, (error: Error) => Promise<void> | void>;\n  }\n>();\n\n/**\n * AsyncLocalStorage for workflow context (async-safe)\n *\n * This replaces the previous module-level variable which was NOT safe for\n * concurrent workflows. AsyncLocalStorage ensures each async execution chain\n * has its own isolated workflow context.\n */\nconst workflowContextStorage =\n  new nodeAsyncHooks.AsyncLocalStorage<WorkflowContext>();\n\n// ============================================================================\n// Workflow Helper\n// ============================================================================\n\n/**\n * Create a traced workflow function\n *\n * Wraps business logic in a workflow span with automatic step tracking,\n * correlation via workflow ID, and compensation support.\n *\n * @param config - Workflow configuration\n * @returns Factory function that wraps your workflow logic\n *\n * @example Order fulfillment workflow\n * ```typescript\n * export const fulfillOrder = traceWorkflow({\n *   name: 'OrderFulfillment',\n *   workflowId: (order) => order.id,\n *   version: '2.0',\n * })(ctx => async (order: Order) => {\n *   ctx.setAttribute('order.total', order.total);\n *\n *   await validateOrder(order);\n *   await processPayment(order);\n *   await fulfillItems(order);\n *   await notifyCustomer(order);\n *\n *   return { success: true, orderId: order.id };\n * });\n * ```\n */\nexport function traceWorkflow<TConfigArgs extends unknown[] = unknown[]>(\n  config: WorkflowConfig<TConfigArgs>,\n) {\n  if (!config || typeof config !== 'object') {\n    throw new TypeError('traceWorkflow: config must be an object');\n  }\n  if (typeof config.name !== 'string' || config.name.trim() === '') {\n    throw new TypeError(\n      'traceWorkflow: config.name must be a non-empty string',\n    );\n  }\n  if (\n    typeof config.workflowId !== 'string' &&\n    typeof config.workflowId !== 'function'\n  ) {\n    throw new TypeError(\n      'traceWorkflow: config.workflowId must be a string or function',\n    );\n  }\n  const spanName = `workflow.${config.name}`;\n\n  return <TArgs extends TConfigArgs, TReturn>(\n    fnFactory: (ctx: WorkflowContext) => (...args: TArgs) => Promise<TReturn>,\n  ): ((...args: TArgs) => Promise<TReturn>) => {\n    assertTraceFactory('traceWorkflow', fnFactory);\n    return withTracing<TArgs, TReturn>({ name: spanName })((baseCtx) => {\n      return async (...args: TArgs) => {\n        // Generate or extract workflow ID\n        const workflowId =\n          typeof config.workflowId === 'function'\n            ? config.workflowId(...args)\n            : config.workflowId;\n\n        // Create workflow context\n        const ctx = createWorkflowContext(baseCtx, config.name, workflowId);\n\n        // Set workflow attributes\n        ctx.setAttribute('workflow.name', config.name);\n        ctx.setAttribute('workflow.id', workflowId);\n        if (config.version) {\n          ctx.setAttribute('workflow.version', config.version);\n        }\n        ctx.setAttribute('workflow.status', 'running');\n\n        // Set custom attributes\n        if (config.attributes) {\n          for (const [key, value] of Object.entries(config.attributes)) {\n            if (value !== undefined) {\n              ctx.setAttribute(key, value as string | number | boolean);\n            }\n          }\n        }\n\n        // Run workflow in AsyncLocalStorage context for async-safety\n        // This ensures concurrent workflows have isolated contexts\n        return workflowContextStorage.run(ctx, async () => {\n          try {\n            // Execute workflow\n            const userFn = fnFactory(ctx);\n            assertTraceFactory('traceWorkflow', userFn, 'result');\n            const result = await userFn(...args);\n\n            // Mark as completed\n            ctx.setWorkflowStatus('completed');\n            config.onComplete?.(ctx, result);\n\n            return result;\n          } catch (error) {\n            // Mark as failed\n            ctx.setWorkflowStatus('failed');\n            config.onFailed?.(ctx, error as Error);\n\n            // Check if we have compensations to run\n            const state = getWorkflowState();\n            if (state && state.compensations.size > 0) {\n              ctx.setWorkflowStatus('compensating');\n              config.onCompensating?.(ctx);\n\n              try {\n                await ctx.compensate(error as Error);\n                ctx.setWorkflowStatus('compensated');\n              } catch (compensationError) {\n                ctx.setWorkflowStatus('compensation_failed');\n                ctx.setAttribute(\n                  'workflow.compensation.error',\n                  String(compensationError),\n                );\n              }\n            }\n\n            throw error;\n          }\n        });\n      };\n    }) as (...args: TArgs) => Promise<TReturn>;\n  };\n}\n\n/**\n * Create a traced workflow step\n *\n * Wraps step logic with automatic linking to previous steps,\n * compensation registration, and status tracking.\n *\n * @param config - Step configuration\n * @returns Factory function that wraps your step logic\n *\n * @example Step with compensation\n * ```typescript\n * const chargePayment = traceStep({\n *   name: 'ChargePayment',\n *   linkToPrevious: true,\n *   compensate: async (error) => {\n *     await paymentService.refund(paymentId);\n *   },\n * })(async (amount: number) => {\n *   return await paymentService.charge(amount);\n * });\n * ```\n */\ntype StepHandler<TArgs extends unknown[], TReturn> = (\n  ...args: TArgs\n) => TReturn | Promise<TReturn>;\n\nexport function traceStep(\n  config: StepConfig,\n): <TArgs extends unknown[], TReturn>(\n  handler: StepHandler<TArgs, TReturn>,\n) => StepHandler<TArgs, TReturn> {\n  if (!config || typeof config !== 'object') {\n    throw new TypeError('traceStep: config must be an object');\n  }\n  if (typeof config.name !== 'string' || config.name.trim() === '') {\n    throw new TypeError('traceStep: config.name must be a non-empty string');\n  }\n\n  return (<TArgs extends unknown[], TReturn>(\n    handler: StepHandler<TArgs, TReturn>,\n  ): StepHandler<TArgs, TReturn> => {\n    if (typeof handler !== 'function') {\n      throw new TypeError(\n        'traceStep(config)(handler): handler must be a function',\n      );\n    }\n    const spanName = `step.${config.name}`;\n\n    return withTracing<TArgs, TReturn>({ name: spanName })((baseCtx) => {\n      return async (...args: TArgs) => {\n        // Get workflow context from AsyncLocalStorage (async-safe)\n        const workflowCtx = workflowContextStorage.getStore() ?? null;\n\n        // Create step context\n        const ctx = createStepContext(baseCtx, config, workflowCtx);\n\n        // Set step attributes\n        ctx.setAttribute('workflow.step.name', config.name);\n        ctx.setAttribute('workflow.step.index', ctx.getStepIndex());\n        ctx.setAttribute('workflow.step.status', 'running');\n\n        if (config.description) {\n          ctx.setAttribute('workflow.step.description', config.description);\n        }\n\n        if (config.idempotent) {\n          ctx.setAttribute('workflow.step.idempotent', true);\n        }\n\n        // Set custom attributes\n        if (config.attributes) {\n          for (const [key, value] of Object.entries(config.attributes)) {\n            if (value !== undefined) {\n              ctx.setAttribute(key, value as string | number | boolean);\n            }\n          }\n        }\n\n        // Link to previous steps\n        await addStepLinks(ctx, config, workflowCtx);\n\n        // Register compensation if provided\n        if (config.compensate && workflowCtx) {\n          const compensate = config.compensate;\n          workflowCtx.registerCompensation(config.name, (error) => {\n            if (compensate.length >= 2) {\n              return (\n                compensate as (\n                  stepCtx: StepContext,\n                  cause: Error,\n                ) => Promise<void> | void\n              )(ctx, error);\n            }\n            return (compensate as (cause: Error) => Promise<void> | void)(\n              error,\n            );\n          });\n        }\n\n        // Execute with optional retry\n        let lastError: Error | undefined;\n        const maxAttempts = config.retry?.maxAttempts ?? 1;\n\n        for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n          try {\n            if (attempt > 1) {\n              ctx.setAttribute('workflow.step.retry_attempt', attempt);\n              emitCorrelatedEvent(ctx, 'step_retry', {\n                'workflow.step.attempt': attempt,\n                'workflow.step.max_attempts': maxAttempts,\n              });\n\n              // Backoff\n              if (config.retry?.backoffMs) {\n                await sleep(config.retry.backoffMs * attempt);\n              }\n            }\n\n            // The step is a plain handler; it receives its real arguments.\n            // Reach the step span via getActiveTraceContext() inside the body.\n            const result = await handler(...args);\n\n            // Mark as completed\n            ctx.setAttribute('workflow.step.status', 'completed');\n            ctx.complete();\n            config.onComplete?.(ctx);\n\n            return result;\n          } catch (error) {\n            lastError = error as Error;\n\n            if (attempt < maxAttempts) {\n              emitCorrelatedEvent(ctx, 'step_retry_scheduled', {\n                'workflow.step.error': String(error),\n                'workflow.step.attempt': attempt,\n              });\n            }\n          }\n        }\n\n        // All attempts failed\n        ctx.setAttribute('workflow.step.status', 'failed');\n        ctx.setAttribute('workflow.step.error', String(lastError));\n        config.onFailed?.(ctx, lastError!);\n\n        throw lastError;\n      };\n    });\n  }) as <TFunctionArgs extends unknown[], TFunctionReturn>(\n    handler: StepHandler<TFunctionArgs, TFunctionReturn>,\n  ) => StepHandler<TFunctionArgs, TFunctionReturn>;\n}\n\n// ============================================================================\n// Context Creation\n// ============================================================================\n\n/**\n * Create workflow-extended context\n */\nfunction createWorkflowContext(\n  baseCtx: TraceContext,\n  workflowName: string,\n  workflowId: string,\n): WorkflowContext {\n  // Initialize state\n  const span = getActiveSpan();\n  const state = {\n    workflowId,\n    workflowName,\n    status: 'running' as WorkflowStatus,\n    steps: new Map<string, StepMetadata>(),\n    stepCounter: 0,\n    compensations: new Map<string, (error: Error) => Promise<void> | void>(),\n  };\n\n  if (span) {\n    workflowStates.set(span, state);\n  }\n\n  return {\n    ...baseCtx,\n\n    getWorkflowId(): string {\n      return workflowId;\n    },\n\n    getWorkflowName(): string {\n      return workflowName;\n    },\n\n    getStatus(): WorkflowStatus {\n      return state.status;\n    },\n\n    completeStep(stepName: string): void {\n      let step = state.steps.get(stepName);\n      if (!step) {\n        // Auto-create step entry for manually managed steps\n        // (when using registerCompensation without traceStep)\n        step = {\n          name: stepName,\n          index: state.stepCounter++,\n          status: 'pending',\n          startTime: Date.now(),\n        };\n        state.steps.set(stepName, step);\n      }\n      step.status = 'completed';\n      step.endTime = Date.now();\n\n      // Capture span context for linking\n      const currentSpan = getActiveSpan();\n      if (currentSpan) {\n        step.spanContext = currentSpan.spanContext();\n      }\n    },\n\n    getPreviousStep(stepName?: string): SpanContext | null {\n      if (stepName) {\n        const step = state.steps.get(stepName);\n        return step?.spanContext ?? null;\n      }\n\n      // Get last completed step\n      let lastStep: StepMetadata | null = null;\n      for (const step of state.steps.values()) {\n        if (\n          step.status === 'completed' &&\n          (!lastStep || step.index > lastStep.index)\n        ) {\n          lastStep = step;\n        }\n      }\n\n      return lastStep?.spanContext ?? null;\n    },\n\n    getCompletedSteps(): string[] {\n      const completed: string[] = [];\n      for (const [name, step] of state.steps) {\n        if (step.status === 'completed') {\n          completed.push(name);\n        }\n      }\n      return completed.toSorted(\n        (a, b) =>\n          (state.steps.get(a)?.index ?? 0) - (state.steps.get(b)?.index ?? 0),\n      );\n    },\n\n    registerCompensation(\n      stepName: string,\n      handler: (error: Error) => Promise<void> | void,\n    ): void {\n      state.compensations.set(stepName, handler);\n    },\n\n    async compensate(error: Error): Promise<void> {\n      // Execute compensations in reverse order\n      const compensationOrder = [...state.compensations.entries()].toReversed();\n\n      for (const [stepName, handler] of compensationOrder) {\n        const step = state.steps.get(stepName);\n        if (step && step.status === 'completed') {\n          try {\n            emitCorrelatedEvent(baseCtx, 'compensation_started', {\n              'workflow.step.name': stepName,\n            });\n\n            await Promise.resolve(handler(error));\n\n            this.recordCompensation(stepName, true);\n            step.status = 'compensated';\n          } catch (compensationError) {\n            this.recordCompensation(\n              stepName,\n              false,\n              compensationError as Error,\n            );\n            throw compensationError;\n          }\n        }\n      }\n    },\n\n    recordCompensation(\n      stepName: string,\n      success: boolean,\n      error?: Error,\n    ): void {\n      emitCorrelatedEvent(baseCtx, 'compensation_completed', {\n        'workflow.step.name': stepName,\n        'workflow.compensation.success': success,\n        ...(error && { 'workflow.compensation.error': String(error) }),\n      });\n\n      baseCtx.setAttribute(\n        `workflow.compensation.${stepName}`,\n        success ? 'success' : 'failed',\n      );\n    },\n\n    setWorkflowStatus(status: WorkflowStatus): void {\n      state.status = status;\n      baseCtx.setAttribute('workflow.status', status);\n\n      emitCorrelatedEvent(baseCtx, 'workflow_status_changed', {\n        'workflow.status': status,\n      });\n    },\n  };\n}\n\n/**\n * Create step-extended context\n */\nfunction createStepContext(\n  baseCtx: TraceContext,\n  config: StepConfig,\n  workflowCtx: WorkflowContext | null,\n): StepContext {\n  // Determine step index\n  let stepIndex = config.index ?? 0;\n  if (workflowCtx) {\n    const span = getActiveSpan();\n    if (span) {\n      const state = workflowStates.get(span);\n      if (state) {\n        stepIndex = config.index ?? state.stepCounter++;\n      }\n    }\n  }\n\n  // Register step metadata\n  if (workflowCtx) {\n    const wfSpan = getActiveSpan();\n    if (wfSpan) {\n      const state = workflowStates.get(wfSpan);\n      if (state) {\n        state.steps.set(config.name, {\n          name: config.name,\n          index: stepIndex,\n          status: 'running',\n          startTime: Date.now(),\n          compensate: config.compensate,\n        });\n      }\n    }\n  }\n\n  return {\n    ...baseCtx,\n\n    getStepName(): string {\n      return config.name;\n    },\n\n    getStepIndex(): number {\n      return stepIndex;\n    },\n\n    complete(): void {\n      if (workflowCtx) {\n        workflowCtx.completeStep(config.name);\n      }\n    },\n\n    skip(reason?: string): void {\n      baseCtx.setAttribute('workflow.step.status', 'skipped');\n      if (reason) {\n        baseCtx.setAttribute('workflow.step.skip_reason', reason);\n      }\n      emitCorrelatedEvent(baseCtx, 'step_skipped', {\n        'workflow.step.name': config.name,\n        ...(reason && { 'workflow.step.skip_reason': reason }),\n      });\n    },\n\n    getWorkflowContext(): WorkflowContext | null {\n      return workflowCtx;\n    },\n  };\n}\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Get workflow state from context\n */\nfunction getWorkflowState() {\n  const span = getActiveSpan();\n  return span ? workflowStates.get(span) : null;\n}\n\n/**\n * Add links to previous steps\n */\nasync function addStepLinks(\n  ctx: StepContext,\n  config: StepConfig,\n  workflowCtx: WorkflowContext | null,\n): Promise<void> {\n  if (!workflowCtx) return;\n\n  const links: Link[] = [];\n\n  // Link to previous step\n  if (config.linkToPrevious) {\n    const prevSpanContext = workflowCtx.getPreviousStep();\n    if (prevSpanContext) {\n      links.push({\n        context: prevSpanContext,\n        attributes: {\n          'workflow.link.type': 'sequence',\n        },\n      });\n    }\n  }\n\n  // Link to specific steps\n  if (config.linkTo) {\n    const stepNames = Array.isArray(config.linkTo)\n      ? config.linkTo\n      : [config.linkTo];\n\n    for (const stepName of stepNames) {\n      const spanContext = workflowCtx.getPreviousStep(stepName);\n      if (spanContext) {\n        links.push({\n          context: spanContext,\n          attributes: {\n            'workflow.link.type': 'dependency',\n            'workflow.link.step': stepName,\n          },\n        });\n      }\n    }\n  }\n\n  // Add all links\n  if (links.length > 0) {\n    ctx.addLinks(links);\n  }\n}\n\n/**\n * Sleep utility for retry backoff\n */\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// ============================================================================\n// Convenience Exports\n// ============================================================================\n\n/**\n * Get current workflow context (if inside a workflow)\n *\n * Uses AsyncLocalStorage to ensure async-safety when multiple\n * workflows are running concurrently.\n */\nexport function getCurrentWorkflowContext(): WorkflowContext | null {\n  return workflowContextStorage.getStore() ?? null;\n}\n\n/**\n * Check if currently executing inside a workflow\n *\n * Uses AsyncLocalStorage to ensure async-safety when multiple\n * workflows are running concurrently.\n */\nexport function isInWorkflow(): boolean {\n  return workflowContextStorage.getStore() !== undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+OA,MAAM,iCAAiB,IAAI,QAUzB;;;;;;;;AASF,MAAM,yBACJ,IAAI,eAAe,kBAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCxD,SAAgB,cACd,QACA;CACA,IAAI,CAAC,UAAU,OAAO,WAAW,UAC/B,MAAM,IAAI,UAAU,yCAAyC;CAE/D,IAAI,OAAO,OAAO,SAAS,YAAY,OAAO,KAAK,KAAK,MAAM,IAC5D,MAAM,IAAI,UACR,uDACF;CAEF,IACE,OAAO,OAAO,eAAe,YAC7B,OAAO,OAAO,eAAe,YAE7B,MAAM,IAAI,UACR,+DACF;CAEF,MAAM,WAAW,YAAY,OAAO;CAEpC,QACE,cAC2C;EAC3C,mBAAmB,iBAAiB,SAAS;EAC7C,OAAO,YAA4B,EAAE,MAAM,SAAS,CAAC,CAAC,EAAE,YAAY;GAClE,OAAO,OAAO,GAAG,SAAgB;IAE/B,MAAM,aACJ,OAAO,OAAO,eAAe,aACzB,OAAO,WAAW,GAAG,IAAI,IACzB,OAAO;IAGb,MAAM,MAAM,sBAAsB,SAAS,OAAO,MAAM,UAAU;IAGlE,IAAI,aAAa,iBAAiB,OAAO,IAAI;IAC7C,IAAI,aAAa,eAAe,UAAU;IAC1C,IAAI,OAAO,SACT,IAAI,aAAa,oBAAoB,OAAO,OAAO;IAErD,IAAI,aAAa,mBAAmB,SAAS;IAG7C,IAAI,OAAO,YACT;UAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,UAAU,GACzD,IAAI,UAAU,QACZ,IAAI,aAAa,KAAK,KAAkC;IAE5D;IAKF,OAAO,uBAAuB,IAAI,KAAK,YAAY;KACjD,IAAI;MAEF,MAAM,SAAS,UAAU,GAAG;MAC5B,mBAAmB,iBAAiB,QAAQ,QAAQ;MACpD,MAAM,SAAS,MAAM,OAAO,GAAG,IAAI;MAGnC,IAAI,kBAAkB,WAAW;MACjC,OAAO,aAAa,KAAK,MAAM;MAE/B,OAAO;KACT,SAAS,OAAO;MAEd,IAAI,kBAAkB,QAAQ;MAC9B,OAAO,WAAW,KAAK,KAAc;MAGrC,MAAM,QAAQ,iBAAiB;MAC/B,IAAI,SAAS,MAAM,cAAc,OAAO,GAAG;OACzC,IAAI,kBAAkB,cAAc;OACpC,OAAO,iBAAiB,GAAG;OAE3B,IAAI;QACF,MAAM,IAAI,WAAW,KAAc;QACnC,IAAI,kBAAkB,aAAa;OACrC,SAAS,mBAAmB;QAC1B,IAAI,kBAAkB,qBAAqB;QAC3C,IAAI,aACF,+BACA,OAAO,iBAAiB,CAC1B;OACF;MACF;MAEA,MAAM;KACR;IACF,CAAC;GACH;EACF,CAAC;CACH;AACF;AA4BA,SAAgB,UACd,QAG+B;CAC/B,IAAI,CAAC,UAAU,OAAO,WAAW,UAC/B,MAAM,IAAI,UAAU,qCAAqC;CAE3D,IAAI,OAAO,OAAO,SAAS,YAAY,OAAO,KAAK,KAAK,MAAM,IAC5D,MAAM,IAAI,UAAU,mDAAmD;CAGzE,SACE,YACgC;EAChC,IAAI,OAAO,YAAY,YACrB,MAAM,IAAI,UACR,wDACF;EAIF,OAAO,YAA4B,EAAE,MAAM,QAFlB,OAAO,OAEoB,CAAC,CAAC,EAAE,YAAY;GAClE,OAAO,OAAO,GAAG,SAAgB;IAE/B,MAAM,cAAc,uBAAuB,SAAS,KAAK;IAGzD,MAAM,MAAM,kBAAkB,SAAS,QAAQ,WAAW;IAG1D,IAAI,aAAa,sBAAsB,OAAO,IAAI;IAClD,IAAI,aAAa,uBAAuB,IAAI,aAAa,CAAC;IAC1D,IAAI,aAAa,wBAAwB,SAAS;IAElD,IAAI,OAAO,aACT,IAAI,aAAa,6BAA6B,OAAO,WAAW;IAGlE,IAAI,OAAO,YACT,IAAI,aAAa,4BAA4B,IAAI;IAInD,IAAI,OAAO,YACT;UAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,UAAU,GACzD,IAAI,UAAU,QACZ,IAAI,aAAa,KAAK,KAAkC;IAE5D;IAIF,MAAM,aAAa,KAAK,QAAQ,WAAW;IAG3C,IAAI,OAAO,cAAc,aAAa;KACpC,MAAM,aAAa,OAAO;KAC1B,YAAY,qBAAqB,OAAO,OAAO,UAAU;MACvD,IAAI,WAAW,UAAU,GACvB,OACE,WAIA,KAAK,KAAK;MAEd,OAAQ,WACN,KACF;KACF,CAAC;IACH;IAGA,IAAI;IACJ,MAAM,cAAc,OAAO,OAAO,eAAe;IAEjD,KAAK,IAAI,UAAU,GAAG,WAAW,aAAa,WAC5C,IAAI;KACF,IAAI,UAAU,GAAG;MACf,IAAI,aAAa,+BAA+B,OAAO;MACvD,oBAAoB,KAAK,cAAc;OACrC,yBAAyB;OACzB,8BAA8B;MAChC,CAAC;MAGD,IAAI,OAAO,OAAO,WAChB,MAAM,MAAM,OAAO,MAAM,YAAY,OAAO;KAEhD;KAIA,MAAM,SAAS,MAAM,QAAQ,GAAG,IAAI;KAGpC,IAAI,aAAa,wBAAwB,WAAW;KACpD,IAAI,SAAS;KACb,OAAO,aAAa,GAAG;KAEvB,OAAO;IACT,SAAS,OAAO;KACd,YAAY;KAEZ,IAAI,UAAU,aACZ,oBAAoB,KAAK,wBAAwB;MAC/C,uBAAuB,OAAO,KAAK;MACnC,yBAAyB;KAC3B,CAAC;IAEL;IAIF,IAAI,aAAa,wBAAwB,QAAQ;IACjD,IAAI,aAAa,uBAAuB,OAAO,SAAS,CAAC;IACzD,OAAO,WAAW,KAAK,SAAU;IAEjC,MAAM;GACR;EACF,CAAC;CACH;AAGF;;;;AASA,SAAS,sBACP,SACA,cACA,YACiB;CAEjB,MAAM,OAAO,cAAc;CAC3B,MAAM,QAAQ;EACZ;EACA;EACA,QAAQ;EACR,uBAAO,IAAI,IAA0B;EACrC,aAAa;EACb,+BAAe,IAAI,IAAoD;CACzE;CAEA,IAAI,MACF,eAAe,IAAI,MAAM,KAAK;CAGhC,OAAO;EACL,GAAG;EAEH,gBAAwB;GACtB,OAAO;EACT;EAEA,kBAA0B;GACxB,OAAO;EACT;EAEA,YAA4B;GAC1B,OAAO,MAAM;EACf;EAEA,aAAa,UAAwB;GACnC,IAAI,OAAO,MAAM,MAAM,IAAI,QAAQ;GACnC,IAAI,CAAC,MAAM;IAGT,OAAO;KACL,MAAM;KACN,OAAO,MAAM;KACb,QAAQ;KACR,WAAW,KAAK,IAAI;IACtB;IACA,MAAM,MAAM,IAAI,UAAU,IAAI;GAChC;GACA,KAAK,SAAS;GACd,KAAK,UAAU,KAAK,IAAI;GAGxB,MAAM,cAAc,cAAc;GAClC,IAAI,aACF,KAAK,cAAc,YAAY,YAAY;EAE/C;EAEA,gBAAgB,UAAuC;GACrD,IAAI,UAEF,OADa,MAAM,MAAM,IAAI,QACnB,CAAC,EAAE,eAAe;GAI9B,IAAI,WAAgC;GACpC,KAAK,MAAM,QAAQ,MAAM,MAAM,OAAO,GACpC,IACE,KAAK,WAAW,gBACf,CAAC,YAAY,KAAK,QAAQ,SAAS,QAEpC,WAAW;GAIf,OAAO,UAAU,eAAe;EAClC;EAEA,oBAA8B;GAC5B,MAAM,YAAsB,CAAC;GAC7B,KAAK,MAAM,CAAC,MAAM,SAAS,MAAM,OAC/B,IAAI,KAAK,WAAW,aAClB,UAAU,KAAK,IAAI;GAGvB,OAAO,UAAU,UACd,GAAG,OACD,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,SAAS,MAAM,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,SAAS,EACrE;EACF;EAEA,qBACE,UACA,SACM;GACN,MAAM,cAAc,IAAI,UAAU,OAAO;EAC3C;EAEA,MAAM,WAAW,OAA6B;GAE5C,MAAM,oBAAoB,CAAC,GAAG,MAAM,cAAc,QAAQ,CAAC,CAAC,CAAC,WAAW;GAExE,KAAK,MAAM,CAAC,UAAU,YAAY,mBAAmB;IACnD,MAAM,OAAO,MAAM,MAAM,IAAI,QAAQ;IACrC,IAAI,QAAQ,KAAK,WAAW,aAC1B,IAAI;KACF,oBAAoB,SAAS,wBAAwB,EACnD,sBAAsB,SACxB,CAAC;KAED,MAAM,QAAQ,QAAQ,QAAQ,KAAK,CAAC;KAEpC,KAAK,mBAAmB,UAAU,IAAI;KACtC,KAAK,SAAS;IAChB,SAAS,mBAAmB;KAC1B,KAAK,mBACH,UACA,OACA,iBACF;KACA,MAAM;IACR;GAEJ;EACF;EAEA,mBACE,UACA,SACA,OACM;GACN,oBAAoB,SAAS,0BAA0B;IACrD,sBAAsB;IACtB,iCAAiC;IACjC,GAAI,SAAS,EAAE,+BAA+B,OAAO,KAAK,EAAE;GAC9D,CAAC;GAED,QAAQ,aACN,yBAAyB,YACzB,UAAU,YAAY,QACxB;EACF;EAEA,kBAAkB,QAA8B;GAC9C,MAAM,SAAS;GACf,QAAQ,aAAa,mBAAmB,MAAM;GAE9C,oBAAoB,SAAS,2BAA2B,EACtD,mBAAmB,OACrB,CAAC;EACH;CACF;AACF;;;;AAKA,SAAS,kBACP,SACA,QACA,aACa;CAEb,IAAI,YAAY,OAAO,SAAS;CAChC,IAAI,aAAa;EACf,MAAM,OAAO,cAAc;EAC3B,IAAI,MAAM;GACR,MAAM,QAAQ,eAAe,IAAI,IAAI;GACrC,IAAI,OACF,YAAY,OAAO,SAAS,MAAM;EAEtC;CACF;CAGA,IAAI,aAAa;EACf,MAAM,SAAS,cAAc;EAC7B,IAAI,QAAQ;GACV,MAAM,QAAQ,eAAe,IAAI,MAAM;GACvC,IAAI,OACF,MAAM,MAAM,IAAI,OAAO,MAAM;IAC3B,MAAM,OAAO;IACb,OAAO;IACP,QAAQ;IACR,WAAW,KAAK,IAAI;IACpB,YAAY,OAAO;GACrB,CAAC;EAEL;CACF;CAEA,OAAO;EACL,GAAG;EAEH,cAAsB;GACpB,OAAO,OAAO;EAChB;EAEA,eAAuB;GACrB,OAAO;EACT;EAEA,WAAiB;GACf,IAAI,aACF,YAAY,aAAa,OAAO,IAAI;EAExC;EAEA,KAAK,QAAuB;GAC1B,QAAQ,aAAa,wBAAwB,SAAS;GACtD,IAAI,QACF,QAAQ,aAAa,6BAA6B,MAAM;GAE1D,oBAAoB,SAAS,gBAAgB;IAC3C,sBAAsB,OAAO;IAC7B,GAAI,UAAU,EAAE,6BAA6B,OAAO;GACtD,CAAC;EACH;EAEA,qBAA6C;GAC3C,OAAO;EACT;CACF;AACF;;;;AASA,SAAS,mBAAmB;CAC1B,MAAM,OAAO,cAAc;CAC3B,OAAO,OAAO,eAAe,IAAI,IAAI,IAAI;AAC3C;;;;AAKA,eAAe,aACb,KACA,QACA,aACe;CACf,IAAI,CAAC,aAAa;CAElB,MAAM,QAAgB,CAAC;CAGvB,IAAI,OAAO,gBAAgB;EACzB,MAAM,kBAAkB,YAAY,gBAAgB;EACpD,IAAI,iBACF,MAAM,KAAK;GACT,SAAS;GACT,YAAY,EACV,sBAAsB,WACxB;EACF,CAAC;CAEL;CAGA,IAAI,OAAO,QAAQ;EACjB,MAAM,YAAY,MAAM,QAAQ,OAAO,MAAM,IACzC,OAAO,SACP,CAAC,OAAO,MAAM;EAElB,KAAK,MAAM,YAAY,WAAW;GAChC,MAAM,cAAc,YAAY,gBAAgB,QAAQ;GACxD,IAAI,aACF,MAAM,KAAK;IACT,SAAS;IACT,YAAY;KACV,sBAAsB;KACtB,sBAAsB;IACxB;GACF,CAAC;EAEL;CACF;CAGA,IAAI,MAAM,SAAS,GACjB,IAAI,SAAS,KAAK;AAEtB;;;;AAKA,SAAS,MAAM,IAA2B;CACxC,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;;;;;;;AAYA,SAAgB,4BAAoD;CAClE,OAAO,uBAAuB,SAAS,KAAK;AAC9C;;;;;;;AAQA,SAAgB,eAAwB;CACtC,OAAO,uBAAuB,SAAS,MAAM;AAC/C"}

package/dist/yaml-config.d.cts

@@ -1,6 +1,5 @@
-import { f as SamplingPreset } from "./sampling-DfYhDJij.cjs";
-import { n as OtlpSignal, t as AutotelConfig } from "./init-DSrRmVnz.cjs";
-
+import { h as SamplingPreset } from "./sampling-BR9fkSwx.cjs";
+import { n as OtlpSignal, t as AutotelConfig } from "./init-a4yPDYqC.cjs";
 //#region src/yaml-config.d.ts
 /**
  * YAML config structure

package/dist/yaml-config.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-config.d.cts","names":[],"sources":["../src/yaml-config.ts"],"mappings":";;;;;;;;UAsDiB,UAAA;EACf,OAAA;IACE,IAAA;IACA,OAAA;IACA,WAAA;EAAA;EAEF,QAAA;IACE,QAAA;IACA,QAAA;IACA,OAAA,GAAU,MAAA;IACV,YAAA,GAAe,KAAA;MACb,QAAA;MACA,QAAA;MACA,OAAA,GAAU,MAAA;MACV,OAAA,GAAU,UAAA;IAAA;EAAA;EAGd,QAAA,GAAW,MAAA;EACX,QAAA;IACE,MAAA,GAAS,cAAA;IACT,IAAA;IACA,KAAA;IACA,aAAA;IACA,oBAAA;IACA,kBAAA;IACA,iBAAA;EAAA;EAEF,oBAAA,cAAkC,MAAA;IAAiB,OAAA;EAAA;EACnD,KAAA;AAAA;;;;AA6PsB;AAcxB;;;;AAA6B;;;;;;iBAnDb,cAAA,IAAkB,OAAO,CAAC,aAAA;;;;;;;;;;;;;;;;;iBAmC1B,sBAAA,CACd,QAAA,WACC,OAAO,CAAC,aAAA;;;;;;iBAcK,aAAA"}
+{"version":3,"file":"yaml-config.d.cts","names":[],"sources":["../src/yaml-config.ts"],"mappings":";;;;;;;UAsDiB;EACf;IACE;IACA;IACA;;EAEF;IACE;IACA;IACA,UAAU;IACV,eAAe;MACb;MACA;MACA,UAAU;MACV,UAAU;;;EAGd,WAAW;EACX;IACE,SAAS;IACT;IACA;IACA;IACA;IACA;IACA;;EAEF,kCAAkC;IAAiB;;EACnD;;;;;;;;;;;;;;;;iBAwNc,kBAAkB,QAAQ;;;;;;;;;;;;;;;;;iBAmC1B,uBACd,mBACC,QAAQ;;;;;;iBAcK"}

package/dist/yaml-config.d.ts

@@ -1,6 +1,5 @@
-import { f as SamplingPreset } from "./sampling-CR0Va1VB.js";
-import { n as OtlpSignal, t as AutotelConfig } from "./init-B7u-DjxM.js";
-
+import { h as SamplingPreset } from "./sampling-CP3e7-Yr.js";
+import { n as OtlpSignal, t as AutotelConfig } from "./init-CTyqG9qR.js";
 //#region src/yaml-config.d.ts
 /**
  * YAML config structure

package/dist/yaml-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-config.d.ts","names":[],"sources":["../src/yaml-config.ts"],"mappings":";;;;;;;;UAsDiB,UAAA;EACf,OAAA;IACE,IAAA;IACA,OAAA;IACA,WAAA;EAAA;EAEF,QAAA;IACE,QAAA;IACA,QAAA;IACA,OAAA,GAAU,MAAA;IACV,YAAA,GAAe,KAAA;MACb,QAAA;MACA,QAAA;MACA,OAAA,GAAU,MAAA;MACV,OAAA,GAAU,UAAA;IAAA;EAAA;EAGd,QAAA,GAAW,MAAA;EACX,QAAA;IACE,MAAA,GAAS,cAAA;IACT,IAAA;IACA,KAAA;IACA,aAAA;IACA,oBAAA;IACA,kBAAA;IACA,iBAAA;EAAA;EAEF,oBAAA,cAAkC,MAAA;IAAiB,OAAA;EAAA;EACnD,KAAA;AAAA;;;;AA6PsB;AAcxB;;;;AAA6B;;;;;;iBAnDb,cAAA,IAAkB,OAAO,CAAC,aAAA;;;;;;;;;;;;;;;;;iBAmC1B,sBAAA,CACd,QAAA,WACC,OAAO,CAAC,aAAA;;;;;;iBAcK,aAAA"}
+{"version":3,"file":"yaml-config.d.ts","names":[],"sources":["../src/yaml-config.ts"],"mappings":";;;;;;;UAsDiB;EACf;IACE;IACA;IACA;;EAEF;IACE;IACA;IACA,UAAU;IACV,eAAe;MACb;MACA;MACA,UAAU;MACV,UAAU;;;EAGd,WAAW;EACX;IACE,SAAS;IACT;IACA;IACA;IACA;IACA;IACA;;EAEF,kCAAkC;IAAiB;;EACnD;;;;;;;;;;;;;;;;iBAwNc,kBAAkB,QAAQ;;;;;;;;;;;;;;;;;iBAmC1B,uBACd,mBACC,QAAQ;;;;;;iBAcK"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "4.2.5",
+  "version": "5.0.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,6 +35,11 @@
       "import": "./dist/sampling.js",
       "require": "./dist/sampling.cjs"
     },
+    "./analysis": {
+      "types": "./dist/analysis.d.ts",
+      "import": "./dist/analysis.js",
+      "require": "./dist/analysis.cjs"
+    },
     "./event": {
       "types": "./dist/event.d.ts",
       "import": "./dist/event.js",
@@ -60,6 +65,11 @@
       "import": "./dist/metric.js",
       "require": "./dist/metric.cjs"
     },
+    "./slo": {
+      "types": "./dist/slo.d.ts",
+      "import": "./dist/slo.js",
+      "require": "./dist/slo.cjs"
+    },
     "./metric-testing": {
       "types": "./dist/metric-testing.d.ts",
       "import": "./dist/metric-testing.js",
@@ -280,8 +290,8 @@
     "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-node": "^0.220.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@opentelemetry/semantic-conventions": "^1.42.0",
-    "import-in-the-middle": "^3.3.1"
+    "@opentelemetry/semantic-conventions": "^1.43.0",
+    "import-in-the-middle": "^3.3.2"
   },
   "peerDependencies": {
     "@opentelemetry/auto-instrumentations-node": "^0.78.0",
@@ -336,7 +346,7 @@
     }
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.4",
+    "@arethetypeswrong/cli": "^0.18.5",
     "@edge-runtime/vm": "^5.0.0",
     "@opentelemetry/auto-instrumentations-node": "^0.78.0",
     "@opentelemetry/context-async-hooks": "^2.9.0",
@@ -347,26 +357,26 @@
     "@opentelemetry/resource-detector-container": "^0.8.11",
     "@opentelemetry/resource-detector-gcp": "^0.55.0",
     "@opentelemetry/sdk-trace-node": "^2.9.0",
-    "@swc/core": "^1.15.43",
+    "@swc/core": "^1.15.46",
     "@total-typescript/ts-reset": "^0.6.1",
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/eslint-config-prettier": "^6.11.3",
-    "@types/node": "^26.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.63.0",
-    "@typescript-eslint/parser": "^8.63.0",
+    "@types/node": "^26.1.1",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-unicorn": "^64.0.0",
     "pino": "^10.3.1",
-    "prettier": "^3.9.4",
+    "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.22.3",
-    "tsx": "^4.23.0",
+    "tsdown": "^0.22.12",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.63.0",
+    "typescript-eslint": "^8.65.0",
     "unplugin-swc": "^1.5.9",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.10",
-    "vitest-mock-extended": "^4.0.0",
+    "vitest-mock-extended": "^5.1.0",
     "winston": "^3.19.0",
     "yaml": "^2.9.0"
   },
@@ -384,7 +394,6 @@
     "dev": "tsdown --watch",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
-    "format": "prettier --write .",
     "format:check": "prettier --check src/**/*.ts",
     "type-check": "tsc --noEmit",
     "test": "vitest run --config vitest.unit.config.ts",

package/skills/analyze-traces/SKILL.md

@@ -10,7 +10,7 @@ license: MIT
 
 # Analyze traces
 
-This skill teaches an AI assistant how to read and reason about OpenTelemetry traces produced by autotel — whether they're sitting in a backend, exported to a local JSON dump, or captured in a test.
+This skill teaches an AI assistant how to read and reason about OpenTelemetry traces produced by autotel. Whether they're sitting in a backend, exported to a local JSON dump, or captured in a test.
 
 ## When to use
 
@@ -24,7 +24,7 @@ This skill teaches an AI assistant how to read and reason about OpenTelemetry tr
 
 | Source                         | How to access                                                      |
 | ------------------------------ | ------------------------------------------------------------------ |
-| Local debug dump               | `.autotel/spans/*.ndjson` — one span per line, OTLP JSON shape     |
+| Local debug dump               | `.autotel/spans/*.ndjson`: one span per line, OTLP JSON shape      |
 | `InMemorySpanExporter` (tests) | `exporter.getFinishedSpans()`                                      |
 | Backend (interactive)          | Jaeger / Tempo / Honeycomb UI; Datadog Trace Search; etc.          |
 | Backend (programmatic)         | Honeycomb Query API, Tempo `/api/search`, Datadog Logs / Trace API |
@@ -79,18 +79,47 @@ Key conventions to recognise:
 1. Find the trace: filter `service.name = "<svc>" AND http.route = "<route>" AND status = error` for the last hour.
 2. Open the slowest / latest matching trace.
 3. Inspect the root span's `exception.message` and `exception.stacktrace`.
-4. Walk down the child spans — the deepest span with `status.code = ERROR` is usually the culprit.
+4. Walk down the child spans: the deepest span with `status.code = ERROR` is usually the culprit.
 5. If using `createStructuredError`, look for `code`, `why`, `internal.*` attributes. They usually answer the "why" without you reading code.
 
 ### "Why is endpoint X slow?"
 
 1. Find a slow trace: `service.name = "<svc>" AND http.route = "<route>" AND duration > p99(duration)`.
-2. View the waterfall — pinpoint the longest child span by self-time (not wall time).
+2. View the waterfall: pinpoint the longest child span by self-time (not wall time).
 3. Common offenders:
-   - **Sequential awaits that should be parallel** — sibling spans run end-to-end instead of overlapping.
-   - **N+1 queries** — many short same-named spans (`SELECT * FROM …`) under one parent.
-   - **Cold starts** — `faas.coldstart=true` in Workers or Lambda.
-   - **Tool retries** — gen-ai spans with `gen_ai.response.finish_reasons` containing `error` followed by another call.
+   - **Sequential awaits that should be parallel**: sibling spans run end-to-end instead of overlapping.
+   - **N+1 queries**: many short same-named spans (`SELECT * FROM …`) under one parent.
+   - **Cold starts**: `faas.coldstart=true` in Workers or Lambda.
+   - **Tool retries**: gen-ai spans with `gen_ai.response.finish_reasons` containing `error` followed by another call.
+
+### "Which requests are affected?"
+
+A waterfall explains one slow request. It cannot tell you what the slow ones
+share. Run the core analysis loop instead: split the population on the symptom,
+then score every recorded field by how much the two groups disagree.
+
+```typescript
+import { compareCohorts } from 'autotel/analysis';
+
+const isSlow = (event) => Number(event['checkout.duration_ms']) >= 800;
+
+const ranked = compareCohorts({
+  outlier: events.filter(isSlow),
+  baseline: events.filter((event) => !isSlow(event)),
+});
+// [{ field: 'payment.provider', value: 'bank-beta', difference: 0.67, … }]
+```
+
+Feed it any array of flat records: `span.attributes` from a collector, wide
+events from `getRequestLogger()`, or rows returned by a backend query.
+
+The loop skips fields whose values never repeat. A request id takes a fresh
+value on every event, so it would bury the answer under noise. Bucket durations
+and payload sizes when you instrument them if you want the loop to rank them.
+
+The top row is a hypothesis. A field can move with the problem without causing
+it. You are done when you have named the cohort and confirmed the mechanism in
+two traces drawn from it.
 
 ### "Follow this user across services"
 
@@ -127,10 +156,10 @@ init({ service: 'my-app', debug: 'pretty', spanDumpPath: '.autotel/spans' });
 
 | Check                         | Query / heuristic                                                                                               |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| **Span name cardinality**     | Top-K distinct `name` per service. Anything > a few hundred is a red flag — likely an unnormalised URL.         |
+| **Span name cardinality**     | Top-K distinct `name` per service. Anything > a few hundred is a red flag: likely an unnormalised URL.          |
 | **Per-attribute cardinality** | `unique(attribute_value)` per `attribute_key`. UUIDs / emails / `Date.now()` ids in attributes blow up storage. |
-| **Missing `service.name`**    | Spans where the resource attribute is empty or `"app"` — fix at the SDK init.                                   |
-| **PII smell**                 | Look for raw `@`, leading digit-runs of length 16, or `eyJ` prefixes — your redactor is off.                    |
+| **Missing `service.name`**    | Spans where the resource attribute is empty or `"app"`: fix at the SDK init.                                    |
+| **PII smell**                 | Look for raw `@`, leading digit-runs of length 16, or `eyJ` prefixes: your redactor is off.                     |
 | **Health-check noise**        | Spans with `http.route in (/healthz, /ready)`. Drop with `FilteringSpanProcessor`.                              |
 
 ## Reading gen-ai traces
@@ -161,8 +190,8 @@ If you expected a span and there isn't one:
 
 1. **Sampling.** Did head sampling drop it? Check `sampling.rates` and `recordedSpans` in any subscriber.
 2. **Workers without `waitUntil`.** Did the request return before the exporter flushed? Move to `defineWorkerFetch` / `wrapModule`.
-3. **`instrumentation.disabled = true`** — check env-conditional config.
-4. **Exporter rejected.** Check service logs for `OTLP exporter` 4xx / 5xx — bad token, wrong dataset.
+3. **`instrumentation.disabled = true`**: check env-conditional config.
+4. **Exporter rejected.** Check service logs for `OTLP exporter` 4xx / 5xx: bad token, wrong dataset.
 
 ## Output format
 

package/skills/autotel-core/SKILL.md

@@ -4,7 +4,7 @@ description: >
   When to use trace vs span vs request logger vs events in Autotel. Init once at startup, package exports (autotel, autotel/event, autotel/testing). Use for setup and choosing the right API.
 ---
 
-# Autotel — Core
+# Autotel: Core
 
 OpenTelemetry instrumentation for Node.js and edge. Instrument once; stream to any OTLP backend. Use `trace()`/`span()` for spans, `getRequestLogger()` for one snapshot per request, `createStructuredError`/`parseError` for errors, `track()` for product events.
 
@@ -29,17 +29,19 @@ Backend config rule of thumb: use `endpoint` for one OTLP destination, `destinat
 ## Setup
 
 ```typescript
-import { init, trace, getRequestLogger } from 'autotel';
+import { init, withTracing, getRequestLogger } from 'autotel';
 
 init({ service: 'my-app' });
 
-const handler = trace((ctx) => async (req: Request) => {
-  const log = getRequestLogger(ctx);
-  log.set({ path: req.url });
-  const result = await doWork(req);
-  log.emitNow();
-  return result;
-});
+const handler = withTracing({ name: 'http.request' })(
+  (ctx) => async (req: Request) => {
+    const log = getRequestLogger(ctx);
+    log.set({ path: req.url });
+    const result = await doWork(req);
+    log.emitNow();
+    return result;
+  },
+);
 ```
 
 ## Core Patterns
@@ -47,12 +49,14 @@ const handler = trace((ctx) => async (req: Request) => {
 **Factory pattern when you need context (attributes, request logger):**
 
 ```typescript
-const createUser = trace((ctx) => async (data: UserInput) => {
-  ctx.setAttribute('user.id', data.id);
-  const log = getRequestLogger(ctx);
-  log.set({ user: { id: data.id } });
-  return db.users.create(data);
-});
+const createUser = withTracing({ name: 'user.create' })(
+  (ctx) => async (data: UserInput) => {
+    ctx.setAttribute('user.id', data.id);
+    const log = getRequestLogger(ctx);
+    log.set({ user: { id: data.id } });
+    return db.users.create(data);
+  },
+);
 ```
 
 **Direct pattern when you don't need context:**
@@ -142,7 +146,7 @@ const handler = trace(async (req) => {
 Correct:
 
 ```typescript
-const handler = trace((ctx) => async (req) => {
+const handler = withTracing({ name: 'http.request' })((ctx) => async (req) => {
   const log = getRequestLogger(ctx);
   log.set({ route: req.url });
 });
@@ -156,4 +160,7 @@ Source: docs/AGENT-GUIDE.md
 
 Targets autotel v2.23.x.
 
-See also: autotel-instrumentation/SKILL.md — init and trace/span in depth. autotel-request-logging/SKILL.md — request logger usage.
+See also:
+
+- `autotel-instrumentation/SKILL.md` for init and trace/span in depth
+- `autotel-request-logging/SKILL.md` for request logger usage

package/skills/autotel-events/SKILL.md

@@ -4,7 +4,7 @@ description: >
   track(), Event API, subscribers (e.g. PostHog). Configure subscribers in init(); use track() or Event for product/analytics events.
 ---
 
-# Autotel — Events
+# Autotel: Events
 
 Send product and analytics events with `track(name, attributes)` or the `Event` class from `autotel/event`. Configure subscribers (e.g. PostHog) in `init()`; they receive events automatically.