autotel 6.4.1 → 7.0.0

package/dist/exception-fingerprint.d.cts

@@ -0,0 +1,51 @@
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/exception-fingerprint.d.ts
+/** Attribute the fingerprint is written to. */
+declare const EXCEPTION_FINGERPRINT_ATTRIBUTE = "exception.fingerprint";
+interface ExceptionInput {
+  /** Error class name, e.g. `TypeError`. Defaults to `Error`. */
+  type?: string;
+  /** Error message. Only used for grouping when there is no usable stack. */
+  message?: string;
+  /** Raw stack string, as `Error.stack` produces it. */
+  stack?: string;
+}
+/**
+ * Collapse a path to the part that identifies the code rather than the machine
+ * it ran on: a dependency becomes its package name, and an absolute path
+ * becomes the project-relative one. Without this, the same error fingerprints
+ * differently in CI, in Docker, and on a laptop.
+ */
+declare function normalizeFilePath(filePath: string): string;
+/**
+ * Strip the parts of a message that change on every occurrence, so
+ * `timeout after 341ms` and `timeout after 78ms` are one issue rather than two.
+ */
+declare function normalizeMessage(message: string): string;
+/**
+ * `function@normalized-path` for the top N frames. Line and column are
+ * deliberately dropped: an edit one line above the throw is the same bug.
+ */
+declare function normalizeStackFrames(stack: string, count: number): string[];
+/** 32-bit djb2-style hash, rendered as 8 hex characters. */
+declare function hashFingerprintParts(parts: string[]): string;
+/**
+ * Group key for an exception. Returns `undefined` when there is nothing to
+ * group on, so callers never write an attribute that means "no information".
+ */
+declare function fingerprintException(input: ExceptionInput, frames?: number): string | undefined;
+interface ExceptionFingerprintOptions {
+  /** Stack frames to fingerprint on. @default 5 */
+  frames?: number;
+}
+/**
+ * Span enricher that stamps {@link EXCEPTION_FINGERPRINT_ATTRIBUTE} on every
+ * span that recorded an exception.
+ *
+ * Pass it to `init({ spanEnrichers: [...] })` rather than `spanProcessors`:
+ * enrichers add to the pipeline instead of replacing it, and sit outside the
+ * redaction wrapper so the attribute reaches every exporter.
+ */
+declare function exceptionFingerprint(options?: ExceptionFingerprintOptions): SpanProcessor;
+//#endregion
+export { EXCEPTION_FINGERPRINT_ATTRIBUTE, ExceptionFingerprintOptions, ExceptionInput, exceptionFingerprint, fingerprintException, hashFingerprintParts, normalizeFilePath, normalizeMessage, normalizeStackFrames };

package/dist/exception-fingerprint.d.ts

@@ -0,0 +1,51 @@
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+//#region src/exception-fingerprint.d.ts
+/** Attribute the fingerprint is written to. */
+declare const EXCEPTION_FINGERPRINT_ATTRIBUTE = "exception.fingerprint";
+interface ExceptionInput {
+  /** Error class name, e.g. `TypeError`. Defaults to `Error`. */
+  type?: string;
+  /** Error message. Only used for grouping when there is no usable stack. */
+  message?: string;
+  /** Raw stack string, as `Error.stack` produces it. */
+  stack?: string;
+}
+/**
+ * Collapse a path to the part that identifies the code rather than the machine
+ * it ran on: a dependency becomes its package name, and an absolute path
+ * becomes the project-relative one. Without this, the same error fingerprints
+ * differently in CI, in Docker, and on a laptop.
+ */
+declare function normalizeFilePath(filePath: string): string;
+/**
+ * Strip the parts of a message that change on every occurrence, so
+ * `timeout after 341ms` and `timeout after 78ms` are one issue rather than two.
+ */
+declare function normalizeMessage(message: string): string;
+/**
+ * `function@normalized-path` for the top N frames. Line and column are
+ * deliberately dropped: an edit one line above the throw is the same bug.
+ */
+declare function normalizeStackFrames(stack: string, count: number): string[];
+/** 32-bit djb2-style hash, rendered as 8 hex characters. */
+declare function hashFingerprintParts(parts: string[]): string;
+/**
+ * Group key for an exception. Returns `undefined` when there is nothing to
+ * group on, so callers never write an attribute that means "no information".
+ */
+declare function fingerprintException(input: ExceptionInput, frames?: number): string | undefined;
+interface ExceptionFingerprintOptions {
+  /** Stack frames to fingerprint on. @default 5 */
+  frames?: number;
+}
+/**
+ * Span enricher that stamps {@link EXCEPTION_FINGERPRINT_ATTRIBUTE} on every
+ * span that recorded an exception.
+ *
+ * Pass it to `init({ spanEnrichers: [...] })` rather than `spanProcessors`:
+ * enrichers add to the pipeline instead of replacing it, and sit outside the
+ * redaction wrapper so the attribute reaches every exporter.
+ */
+declare function exceptionFingerprint(options?: ExceptionFingerprintOptions): SpanProcessor;
+//#endregion
+export { EXCEPTION_FINGERPRINT_ATTRIBUTE, ExceptionFingerprintOptions, ExceptionInput, exceptionFingerprint, fingerprintException, hashFingerprintParts, normalizeFilePath, normalizeMessage, normalizeStackFrames };

package/dist/exception-fingerprint.js

@@ -0,0 +1,126 @@
+import { g as nonEmptyString } from "./values-BenyvWKz.js";
+
+//#region src/exception-fingerprint.ts
+/** Attribute the fingerprint is written to. */
+const EXCEPTION_FINGERPRINT_ATTRIBUTE = "exception.fingerprint";
+/**
+* Frames deep enough to separate two different bugs, shallow enough that the
+* same bug reached through different callers still groups.
+*/
+const DEFAULT_FRAMES = 5;
+const NODE_FRAME = /^at\s+(.+?)\s+\((.+?):(\d+):\d+\)$/;
+const ANON_FRAME = /^at\s+(.+?):(\d+):\d+$/;
+const BROWSER_FRAME = /^(.+?)@(.+?):(\d+):\d+$/;
+/**
+* Collapse a path to the part that identifies the code rather than the machine
+* it ran on: a dependency becomes its package name, and an absolute path
+* becomes the project-relative one. Without this, the same error fingerprints
+* differently in CI, in Docker, and on a laptop.
+*/
+function normalizeFilePath(filePath) {
+	const nodeModulesMatch = filePath.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+	if (nodeModulesMatch) return `[npm]/${nodeModulesMatch[1]}`;
+	return filePath.replace(/^.*?\/src\//, "src/").replace(/^.*?\/dist\//, "dist/").replace(/^.*?\/lib\//, "lib/").replace(/^file:\/\//, "");
+}
+/**
+* Strip the parts of a message that change on every occurrence, so
+* `timeout after 341ms` and `timeout after 78ms` are one issue rather than two.
+*/
+function normalizeMessage(message) {
+	return message.replaceAll(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "[UUID]").replaceAll(/\b[0-9a-f]{16,}\b/gi, "[ID]").replaceAll(/\d+/g, "[N]").replaceAll(/"[^"]*"/g, "\"[STR]\"").replaceAll(/'[^']*'/g, "'[STR]'").slice(0, 200);
+}
+/**
+* `function@normalized-path` for the top N frames. Line and column are
+* deliberately dropped: an edit one line above the throw is the same bug.
+*/
+function normalizeStackFrames(stack, count) {
+	const frames = [];
+	for (const line of stack.split("\n")) {
+		if (frames.length >= count) break;
+		const trimmed = line.trim();
+		const node = NODE_FRAME.exec(trimmed);
+		if (node) {
+			frames.push(`${node[1] ?? "anonymous"}@${normalizeFilePath(node[2] ?? "")}`);
+			continue;
+		}
+		const anon = ANON_FRAME.exec(trimmed);
+		if (anon) {
+			frames.push(`anonymous@${normalizeFilePath(anon[1] ?? "")}`);
+			continue;
+		}
+		const browser = BROWSER_FRAME.exec(trimmed);
+		if (browser) frames.push(`${browser[1] ?? "anonymous"}@${normalizeFilePath(browser[2] ?? "")}`);
+	}
+	return frames;
+}
+/** 32-bit djb2-style hash, rendered as 8 hex characters. */
+function hashFingerprintParts(parts) {
+	const value = parts.join("|");
+	let hash = 0;
+	for (let index = 0; index < value.length; index++) {
+		hash = (hash << 5) - hash + value.charCodeAt(index);
+		hash = hash & hash;
+	}
+	return Math.abs(hash).toString(16).padStart(8, "0");
+}
+/**
+* Group key for an exception. Returns `undefined` when there is nothing to
+* group on, so callers never write an attribute that means "no information".
+*/
+function fingerprintException(input, frames = DEFAULT_FRAMES) {
+	const stackFrames = input.stack ? normalizeStackFrames(input.stack, frames) : [];
+	if (stackFrames.length === 0 && !input.message && !input.type) return;
+	const parts = [input.type || "Error"];
+	if (stackFrames.length > 0) parts.push(...stackFrames);
+	else if (input.message) parts.push(normalizeMessage(input.message));
+	return hashFingerprintParts(parts);
+}
+/**
+* Read the error off a finished span, wherever it was recorded: the OTel
+* `exception` event, the `exception.*` attributes autotel-web sets, or the
+* `error.*` attributes structured errors write instead of an event.
+*/
+function readException(span) {
+	const { attributes } = span;
+	const event = span.events?.find((e) => e.name === "exception");
+	const eventAttributes = event?.attributes ?? {};
+	const type = nonEmptyString(attributes["exception.type"]) ?? nonEmptyString(attributes["error.type"]) ?? nonEmptyString(eventAttributes["exception.type"]);
+	const stack = nonEmptyString(attributes["exception.stacktrace"]) ?? nonEmptyString(attributes["exception.stack"]) ?? nonEmptyString(attributes["error.stack"]) ?? nonEmptyString(eventAttributes["exception.stacktrace"]) ?? nonEmptyString(eventAttributes["exception.stack"]);
+	if (!type && !stack && !event) return void 0;
+	return {
+		type,
+		message: nonEmptyString(attributes["exception.message"]) ?? nonEmptyString(attributes["error.message"]) ?? nonEmptyString(eventAttributes["exception.message"]) ?? nonEmptyString(span.status.message),
+		stack
+	};
+}
+/**
+* Span enricher that stamps {@link EXCEPTION_FINGERPRINT_ATTRIBUTE} on every
+* span that recorded an exception.
+*
+* Pass it to `init({ spanEnrichers: [...] })` rather than `spanProcessors`:
+* enrichers add to the pipeline instead of replacing it, and sit outside the
+* redaction wrapper so the attribute reaches every exporter.
+*/
+function exceptionFingerprint(options = {}) {
+	const frames = options.frames ?? DEFAULT_FRAMES;
+	return {
+		onStart(_span, _context) {},
+		onEnd(span) {
+			const { attributes } = span;
+			if (attributes["exception.fingerprint"] !== void 0) return;
+			const exception = readException(span);
+			if (!exception) return;
+			const fingerprint = fingerprintException(exception, frames);
+			if (fingerprint) attributes[EXCEPTION_FINGERPRINT_ATTRIBUTE] = fingerprint;
+		},
+		forceFlush() {
+			return Promise.resolve();
+		},
+		shutdown() {
+			return Promise.resolve();
+		}
+	};
+}
+
+//#endregion
+export { EXCEPTION_FINGERPRINT_ATTRIBUTE, exceptionFingerprint, fingerprintException, hashFingerprintParts, normalizeFilePath, normalizeMessage, normalizeStackFrames };

package/dist/{functional-AT22vCw6.d.ts → functional-CJn2zY4o.d.cts}

@@ -1,6 +1,6 @@
-import { n as TraceContext } from "./trace-context-IuyoPyNq.js";
-import { p as Sampler } from "./sampling-CP3e7-Yr.js";
-import { Span, SpanKind } from "@opentelemetry/api";
+import { n as TraceContext } from "./trace-context-C1Cn1q0y.cjs";
+import { p as Sampler } from "./sampling-CmRdnXUi.cjs";
+import { Attributes, Span, SpanKind } from "@opentelemetry/api";
 //#region src/functional-wrapper.d.ts
 type WrappedFunction<TArgs extends unknown[], TReturn> = (...args: TArgs) => TReturn | Promise<TReturn>;
 /**
@@ -35,9 +35,10 @@ interface TracingOptions<TArgs extends unknown[] = unknown[], TReturn = unknown>
    */
   withMetrics?: boolean;
   /** Extract attributes from function arguments. */
-  attributesFromArgs?: (args: TArgs) => Record<string, unknown>;
+  attributesFromArgs?: (args: TArgs) => Attributes;
   /** Extract attributes from the function result. */
-  attributesFromResult?: (result: TReturn) => Record<string, unknown>;
+  /** Receives the resolved value when the function returns a Promise. */
+  attributesFromResult?: (result: Awaited<TReturn>) => Attributes;
   /**
    * Capture arguments on the span as the truncated JSON `autotel.input`
    * attribute. One argument is captured directly; multiple arguments are an
@@ -72,7 +73,7 @@ interface TracingOptions<TArgs extends unknown[] = unknown[], TReturn = unknown>
    * as `redirect()` and `notFound()`.
    * @default every throw is treated as an error
    */
-  isError?: (error: unknown) => boolean;
+  isError?: (cause: unknown) => boolean;
 }
 /** Options for `instrument()` batch instrumentation. */
 interface InstrumentOptions<T extends Record<string, AnyInstrumentable> = Record<string, AnyInstrumentable>> extends TracingOptions {
@@ -95,6 +96,33 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
 }
 //#endregion
 //#region src/functional.d.ts
+/**
+ * Complete trace context containing trace identifiers and span methods
+ *
+ * The ctx parameter in trace() functions provides:
+ * - traceId, spanId, correlationId from the active span
+ * - Span manipulation methods (setAttribute, setAttributes, setStatus, recordException)
+ *
+ * For custom context, access it directly in your functions (standard OpenTelemetry pattern).
+ *
+ * @example
+ * ```typescript
+ * import { trace } from 'autotel'
+ *
+ * export const createUser = withTracing({})((ctx) => async (data: CreateUserData) => {
+ *   // Get custom context directly (standard OTel approach)
+ *   const userId = getCurrentUserId()
+ *   const tenantId = getCurrentTenant()
+ *
+ *   // Use ctx for span operations and trace IDs
+ *   ctx.setAttribute('user.id', data.id)
+ *   ctx.setAttribute('user.tenant', tenantId)
+ *   console.log(ctx.traceId)  // Trace IDs available
+ * })
+ * ```
+ */
+/** Baggage entries: values that survive the W3C baggage header. */
+type BaggageValues = Record<string, string | number | boolean>;
 /**
  * Get the autotel {@link TraceContext} for the currently active span.
  *
@@ -105,7 +133,7 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
  *
  * @example
  * ```typescript
- * const getUser = trace('getUser', async (id: string) => {
+ * const getUser = trace(async function getUser(id: string) {
  *   getActiveTraceContext()?.setAttribute('user.id', id);
  *   return db.users.find(id);
  * });
@@ -114,34 +142,17 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
  * @see getActiveSpan for the raw OpenTelemetry span
  * @see getRequestLogger which reads the active context when called with no args
  */
-declare function getActiveTraceContext<TBaggage extends Record<string, unknown> | undefined = undefined>(): TraceContext<TBaggage> | undefined;
-/**
- * Context object that lazily evaluates the active span on property access
- *
- * Access trace context directly without function call syntax.
- *
- * @example
- * ```typescript
- * import { trace, ctx } from 'autotel'
- *
- * export const createUser = trace(async (data) => {
- *   // Direct property access - no function call!
- *   if (ctx.traceId) {
- *     ctx.setAttribute('user.id', data.id)
- *     console.log('Trace:', ctx.traceId)
- *   }
- * })
- * ```
- */
+declare function getActiveTraceContext<TBaggage extends BaggageValues | undefined = undefined>(): TraceContext<TBaggage> | undefined;
 declare const ctx: TraceContext;
 /**
- * Wrap a plain function with automatic tracing. The function receives its real
- * arguments; no context parameter is injected. Use
- * {@link getActiveTraceContext} inside the function, or use {@link withTracing}
- * for the explicit `(ctx) => (...args) => result` factory form.
+ * Wrap a plain function with a traced wrapper, or run one named operation
+ * immediately with {@link trace.run}.
  *
- * `trace()` never executes or inspects the function during wrapper
- * construction.
+ * Every `trace(...)` call returns a **wrapper**. Nothing runs until you call
+ * what you get back, so a `trace()` call can never execute your function at
+ * module load. Reach the span from inside the body through the ambient
+ * {@link ctx} - it resolves at any depth, so a helper three frames down sees
+ * the same span without being handed anything.
  *
  * @example Auto-inferred name
  * ```typescript
@@ -150,24 +161,70 @@ declare const ctx: TraceContext;
  * })
  * ```
  *
- * @example Ambient context access
+ * @example Explicit name
  * ```typescript
- * export const createUser = trace(async (data) => {
- *   getActiveTraceContext()?.setAttribute('user.id', data.id)
+ * export const createUser = trace('user.create', async (data) => {
  *   return await db.users.create(data)
  * })
  * ```
  *
- * @example Explicit name
+ * @example Ambient context, at any depth
  * ```typescript
+ * import { trace, ctx } from 'autotel'
+ *
  * export const createUser = trace('user.create', async (data) => {
+ *   ctx.setAttribute('user.id', data.id)
  *   return await db.users.create(data)
  * })
  * ```
+ *
+ * @example Curried, for a shared configuration
+ * ```typescript
+ * const traced = trace({ serviceName: 'users' })
+ * export const createUser = traced(async (data) => db.users.create(data))
+ * ```
+ *
+ * @example One operation, run now - see {@link trace.run}
+ * ```typescript
+ * const user = await trace.run('user.create', async (ctx) => {
+ *   ctx.setAttribute('user.id', input.id)
+ *   return db.users.create(input)
+ * })
+ * ```
+ */
+declare function traceImpl<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl(name: string): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>): (fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+/**
+ * Run one named operation immediately and return its result, with the
+ * {@link TraceContext} passed in.
+ *
+ * This is the counterpart to {@link trace}: `trace(...)` always hands back a
+ * wrapper to call later, `trace.run(...)` runs the operation now. Keeping them
+ * under separate names is deliberate - a single call shape that sometimes
+ * wrapped and sometimes ran is what made dispatch depend on a callback's
+ * parameter name, which a minifier is free to rewrite (#166).
+ *
+ * The body can equally read the ambient {@link ctx}; the parameter is here for
+ * when an explicit binding reads better.
+ *
+ * @example
+ * ```typescript
+ * const user = await trace.run('user.create', async (ctx) => {
+ *   ctx.setAttribute('user.id', input.id)
+ *   return db.users.create(input)
+ * })
+ * ```
  */
-declare function trace$1<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-declare function trace$1<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-declare function trace$1<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function run<TReturn>(name: string, operation: (ctx: TraceContext) => Promise<TReturn>): Promise<TReturn>;
+declare function run<TReturn>(name: string, operation: (ctx: TraceContext) => TReturn): TReturn;
+declare function run<TReturn>(options: TracingOptions<[], TReturn>, operation: (ctx: TraceContext) => Promise<TReturn>): Promise<TReturn>;
+declare function run<TReturn>(options: TracingOptions<[], TReturn>, operation: (ctx: TraceContext) => TReturn): TReturn;
+declare const trace$1: typeof traceImpl & {
+  run: typeof run;
+};
 /**
  * Approach 2: withTracing() - Middleware-style composable wrapper
  *

package/dist/{functional-e6jw5zQj.d.cts → functional-DXy1cHFF.d.ts}

@@ -1,6 +1,6 @@
-import { n as TraceContext } from "./trace-context-IuyoPyNq.cjs";
-import { p as Sampler } from "./sampling-BR9fkSwx.cjs";
-import { Span, SpanKind } from "@opentelemetry/api";
+import { n as TraceContext } from "./trace-context-f89xPJbK.js";
+import { p as Sampler } from "./sampling-CM5S2Lp3.js";
+import { Attributes, Span, SpanKind } from "@opentelemetry/api";
 //#region src/functional-wrapper.d.ts
 type WrappedFunction<TArgs extends unknown[], TReturn> = (...args: TArgs) => TReturn | Promise<TReturn>;
 /**
@@ -35,9 +35,10 @@ interface TracingOptions<TArgs extends unknown[] = unknown[], TReturn = unknown>
    */
   withMetrics?: boolean;
   /** Extract attributes from function arguments. */
-  attributesFromArgs?: (args: TArgs) => Record<string, unknown>;
+  attributesFromArgs?: (args: TArgs) => Attributes;
   /** Extract attributes from the function result. */
-  attributesFromResult?: (result: TReturn) => Record<string, unknown>;
+  /** Receives the resolved value when the function returns a Promise. */
+  attributesFromResult?: (result: Awaited<TReturn>) => Attributes;
   /**
    * Capture arguments on the span as the truncated JSON `autotel.input`
    * attribute. One argument is captured directly; multiple arguments are an
@@ -72,7 +73,7 @@ interface TracingOptions<TArgs extends unknown[] = unknown[], TReturn = unknown>
    * as `redirect()` and `notFound()`.
    * @default every throw is treated as an error
    */
-  isError?: (error: unknown) => boolean;
+  isError?: (cause: unknown) => boolean;
 }
 /** Options for `instrument()` batch instrumentation. */
 interface InstrumentOptions<T extends Record<string, AnyInstrumentable> = Record<string, AnyInstrumentable>> extends TracingOptions {
@@ -95,6 +96,33 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
 }
 //#endregion
 //#region src/functional.d.ts
+/**
+ * Complete trace context containing trace identifiers and span methods
+ *
+ * The ctx parameter in trace() functions provides:
+ * - traceId, spanId, correlationId from the active span
+ * - Span manipulation methods (setAttribute, setAttributes, setStatus, recordException)
+ *
+ * For custom context, access it directly in your functions (standard OpenTelemetry pattern).
+ *
+ * @example
+ * ```typescript
+ * import { trace } from 'autotel'
+ *
+ * export const createUser = withTracing({})((ctx) => async (data: CreateUserData) => {
+ *   // Get custom context directly (standard OTel approach)
+ *   const userId = getCurrentUserId()
+ *   const tenantId = getCurrentTenant()
+ *
+ *   // Use ctx for span operations and trace IDs
+ *   ctx.setAttribute('user.id', data.id)
+ *   ctx.setAttribute('user.tenant', tenantId)
+ *   console.log(ctx.traceId)  // Trace IDs available
+ * })
+ * ```
+ */
+/** Baggage entries: values that survive the W3C baggage header. */
+type BaggageValues = Record<string, string | number | boolean>;
 /**
  * Get the autotel {@link TraceContext} for the currently active span.
  *
@@ -105,7 +133,7 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
  *
  * @example
  * ```typescript
- * const getUser = trace('getUser', async (id: string) => {
+ * const getUser = trace(async function getUser(id: string) {
  *   getActiveTraceContext()?.setAttribute('user.id', id);
  *   return db.users.find(id);
  * });
@@ -114,34 +142,17 @@ interface SingleInstrumentOptions<TFunction extends AnyInstrumentable = AnyInstr
  * @see getActiveSpan for the raw OpenTelemetry span
  * @see getRequestLogger which reads the active context when called with no args
  */
-declare function getActiveTraceContext<TBaggage extends Record<string, unknown> | undefined = undefined>(): TraceContext<TBaggage> | undefined;
-/**
- * Context object that lazily evaluates the active span on property access
- *
- * Access trace context directly without function call syntax.
- *
- * @example
- * ```typescript
- * import { trace, ctx } from 'autotel'
- *
- * export const createUser = trace(async (data) => {
- *   // Direct property access - no function call!
- *   if (ctx.traceId) {
- *     ctx.setAttribute('user.id', data.id)
- *     console.log('Trace:', ctx.traceId)
- *   }
- * })
- * ```
- */
+declare function getActiveTraceContext<TBaggage extends BaggageValues | undefined = undefined>(): TraceContext<TBaggage> | undefined;
 declare const ctx: TraceContext;
 /**
- * Wrap a plain function with automatic tracing. The function receives its real
- * arguments; no context parameter is injected. Use
- * {@link getActiveTraceContext} inside the function, or use {@link withTracing}
- * for the explicit `(ctx) => (...args) => result` factory form.
+ * Wrap a plain function with a traced wrapper, or run one named operation
+ * immediately with {@link trace.run}.
  *
- * `trace()` never executes or inspects the function during wrapper
- * construction.
+ * Every `trace(...)` call returns a **wrapper**. Nothing runs until you call
+ * what you get back, so a `trace()` call can never execute your function at
+ * module load. Reach the span from inside the body through the ambient
+ * {@link ctx} - it resolves at any depth, so a helper three frames down sees
+ * the same span without being handed anything.
  *
  * @example Auto-inferred name
  * ```typescript
@@ -150,24 +161,70 @@ declare const ctx: TraceContext;
  * })
  * ```
  *
- * @example Ambient context access
+ * @example Explicit name
  * ```typescript
- * export const createUser = trace(async (data) => {
- *   getActiveTraceContext()?.setAttribute('user.id', data.id)
+ * export const createUser = trace('user.create', async (data) => {
  *   return await db.users.create(data)
  * })
  * ```
  *
- * @example Explicit name
+ * @example Ambient context, at any depth
  * ```typescript
+ * import { trace, ctx } from 'autotel'
+ *
  * export const createUser = trace('user.create', async (data) => {
+ *   ctx.setAttribute('user.id', data.id)
  *   return await db.users.create(data)
  * })
  * ```
+ *
+ * @example Curried, for a shared configuration
+ * ```typescript
+ * const traced = trace({ serviceName: 'users' })
+ * export const createUser = traced(async (data) => db.users.create(data))
+ * ```
+ *
+ * @example One operation, run now - see {@link trace.run}
+ * ```typescript
+ * const user = await trace.run('user.create', async (ctx) => {
+ *   ctx.setAttribute('user.id', input.id)
+ *   return db.users.create(input)
+ * })
+ * ```
+ */
+declare function traceImpl<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function traceImpl(name: string): <TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+declare function traceImpl<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>): (fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
+/**
+ * Run one named operation immediately and return its result, with the
+ * {@link TraceContext} passed in.
+ *
+ * This is the counterpart to {@link trace}: `trace(...)` always hands back a
+ * wrapper to call later, `trace.run(...)` runs the operation now. Keeping them
+ * under separate names is deliberate - a single call shape that sometimes
+ * wrapped and sometimes ran is what made dispatch depend on a callback's
+ * parameter name, which a minifier is free to rewrite (#166).
+ *
+ * The body can equally read the ambient {@link ctx}; the parameter is here for
+ * when an explicit binding reads better.
+ *
+ * @example
+ * ```typescript
+ * const user = await trace.run('user.create', async (ctx) => {
+ *   ctx.setAttribute('user.id', input.id)
+ *   return db.users.create(input)
+ * })
+ * ```
  */
-declare function trace$1<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-declare function trace$1<TArgs extends unknown[], TReturn>(name: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
-declare function trace$1<TArgs extends unknown[], TReturn>(options: TracingOptions<TArgs, TReturn>, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+declare function run<TReturn>(name: string, operation: (ctx: TraceContext) => Promise<TReturn>): Promise<TReturn>;
+declare function run<TReturn>(name: string, operation: (ctx: TraceContext) => TReturn): TReturn;
+declare function run<TReturn>(options: TracingOptions<[], TReturn>, operation: (ctx: TraceContext) => Promise<TReturn>): Promise<TReturn>;
+declare function run<TReturn>(options: TracingOptions<[], TReturn>, operation: (ctx: TraceContext) => TReturn): TReturn;
+declare const trace$1: typeof traceImpl & {
+  run: typeof run;
+};
 /**
  * Approach 2: withTracing() - Middleware-style composable wrapper
  *