bitfab 0.38.2 → 0.38.4

package/dist/index.d.cts

@@ -1234,7 +1234,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
-    /** Optional list of specific trace IDs to replay (max 100). */
+    /** Optional list of specific trace IDs to replay (max 100). Mutually exclusive with `datasetId`. */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
     name?: string;
@@ -1291,7 +1291,8 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `traceIds`. When
+     * set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -2058,6 +2059,8 @@ interface SpanOptions {
      * real child.
      */
     mockOnReplay?: boolean;
+    /** Optional test run ID included on the span and on the trace it starts. */
+    testRunId?: string;
     /**
      * Record a serializable view of a non-serializable result (e.g. a live
      * stream object) as the span output.
@@ -2099,6 +2102,15 @@ interface SpanMethodDecoratorContext<TThis, TValue> {
 }
 /** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
 type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
+/** Trace-owned configuration for a function discovered beneath `trace()`. */
+interface NodeOptions extends Omit<SpanOptions, "captureWhen"> {
+    /** Whether the enclosing trace captures this call. Defaults to true. */
+    capture?: boolean;
+}
+type StandardNodeMethodDecorator = SpanMethodDecorator;
+type LegacyNodeMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(this: TThis, ...args: TArgs) => TReturn>) => void;
+/** A method decorator produced by {@link Bitfab.node}. */
+type NodeMethodDecorator = StandardNodeMethodDecorator & LegacyNodeMethodDecorator;
 /** Options for experimental automatic subtree tracing. */
 interface TraceOptions {
     /** Root span name. Defaults to the decorated or wrapped function name. */
@@ -2181,6 +2193,36 @@ declare class Bitfab {
      */
     withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
     withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    /**
+     * Configure a transformed class method when it is discovered beneath a
+     * {@link Bitfab.trace} root.
+     *
+     * The decorator creates no span or trace by itself. Beneath an active trace,
+     * it can rename or retype the discovered call, capture its contents, mark it
+     * for recorded-output replay, finalize its output, or omit it while leaving
+     * captured descendants attached to the nearest captured parent.
+     *
+     * @param options - Trace-owned call configuration.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    node(options?: NodeOptions): NodeMethodDecorator;
+    /**
+     * Configure a transformed standalone function when it is discovered beneath
+     * a {@link Bitfab.trace} or {@link Bitfab.withTrace} root.
+     *
+     * This is the function-oriented equivalent of {@link Bitfab.node}. Without
+     * an active automatic trace, the returned function runs normally and never
+     * creates a span or trace. The function must be named so configuration can
+     * be bound to its transformed definition without leaking to a descendant.
+     *
+     * @param optionsOrFn - Node options or the function to configure.
+     * @param maybeFn - Function to configure when options are provided.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    withNode<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    withNode<This, TArgs extends unknown[], TReturn>(options: NodeOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    private resolveNodeConfiguration;
+    private createAutoTraceNode;
     private createAutoTraceRoot;
     private refreshAutoTraceCapturePolicy;
     /**
@@ -2717,7 +2759,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.2";
+declare const __version__ = "0.38.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2785,4 +2827,39 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayProgressItem, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">;
+interface ReplayRegistryContext {
+    /** Values supplied through `--params` and repeated `--param name=value`. */
+    params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+    /** Client instance used by the production traced function. */
+    client: Bitfab;
+    /** The exact traced function production calls. */
+    fn: ReplayFunction;
+    /**
+     * Required for handler-instrumented or otherwise plain callables. Omit for a
+     * `withSpan`-wrapped function and the registry reads the wrapper's key.
+     */
+    traceFunctionKey?: string;
+    /**
+     * Per-function replay behavior and defaults. Put executable configuration
+     * such as `mockOverride` and `adaptInputs` here; command-line values override
+     * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+     */
+    options?: ReplayRegistryOptions;
+    /** Build executable replay behavior from caller-supplied CLI parameters. */
+    optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.d.ts

@@ -1234,7 +1234,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
-    /** Optional list of specific trace IDs to replay (max 100). */
+    /** Optional list of specific trace IDs to replay (max 100). Mutually exclusive with `datasetId`. */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
     name?: string;
@@ -1291,7 +1291,8 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `traceIds`. When
+     * set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -2058,6 +2059,8 @@ interface SpanOptions {
      * real child.
      */
     mockOnReplay?: boolean;
+    /** Optional test run ID included on the span and on the trace it starts. */
+    testRunId?: string;
     /**
      * Record a serializable view of a non-serializable result (e.g. a live
      * stream object) as the span output.
@@ -2099,6 +2102,15 @@ interface SpanMethodDecoratorContext<TThis, TValue> {
 }
 /** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
 type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
+/** Trace-owned configuration for a function discovered beneath `trace()`. */
+interface NodeOptions extends Omit<SpanOptions, "captureWhen"> {
+    /** Whether the enclosing trace captures this call. Defaults to true. */
+    capture?: boolean;
+}
+type StandardNodeMethodDecorator = SpanMethodDecorator;
+type LegacyNodeMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(this: TThis, ...args: TArgs) => TReturn>) => void;
+/** A method decorator produced by {@link Bitfab.node}. */
+type NodeMethodDecorator = StandardNodeMethodDecorator & LegacyNodeMethodDecorator;
 /** Options for experimental automatic subtree tracing. */
 interface TraceOptions {
     /** Root span name. Defaults to the decorated or wrapped function name. */
@@ -2181,6 +2193,36 @@ declare class Bitfab {
      */
     withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
     withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    /**
+     * Configure a transformed class method when it is discovered beneath a
+     * {@link Bitfab.trace} root.
+     *
+     * The decorator creates no span or trace by itself. Beneath an active trace,
+     * it can rename or retype the discovered call, capture its contents, mark it
+     * for recorded-output replay, finalize its output, or omit it while leaving
+     * captured descendants attached to the nearest captured parent.
+     *
+     * @param options - Trace-owned call configuration.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    node(options?: NodeOptions): NodeMethodDecorator;
+    /**
+     * Configure a transformed standalone function when it is discovered beneath
+     * a {@link Bitfab.trace} or {@link Bitfab.withTrace} root.
+     *
+     * This is the function-oriented equivalent of {@link Bitfab.node}. Without
+     * an active automatic trace, the returned function runs normally and never
+     * creates a span or trace. The function must be named so configuration can
+     * be bound to its transformed definition without leaking to a descendant.
+     *
+     * @param optionsOrFn - Node options or the function to configure.
+     * @param maybeFn - Function to configure when options are provided.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    withNode<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    withNode<This, TArgs extends unknown[], TReturn>(options: NodeOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    private resolveNodeConfiguration;
+    private createAutoTraceNode;
     private createAutoTraceRoot;
     private refreshAutoTraceCapturePolicy;
     /**
@@ -2717,7 +2759,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.2";
+declare const __version__ = "0.38.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2785,4 +2827,39 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayProgressItem, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">;
+interface ReplayRegistryContext {
+    /** Values supplied through `--params` and repeated `--param name=value`. */
+    params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+    /** Client instance used by the production traced function. */
+    client: Bitfab;
+    /** The exact traced function production calls. */
+    fn: ReplayFunction;
+    /**
+     * Required for handler-instrumented or otherwise plain callables. Omit for a
+     * `withSpan`-wrapped function and the registry reads the wrapper's key.
+     */
+    traceFunctionKey?: string;
+    /**
+     * Per-function replay behavior and defaults. Put executable configuration
+     * such as `mockOverride` and `adaptInputs` here; command-line values override
+     * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+     */
+    options?: ReplayRegistryOptions;
+    /** Build executable replay behavior from caller-supplied CLI parameters. */
+    optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.js

@@ -16,12 +16,13 @@ import {
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   SUPPORTED_PROVIDERS,
+  defineReplayRegistry,
   finalizers,
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-JSU2Z2Z7.js";
-import "./chunk-GFBQ2AMO.js";
+} from "./chunk-PXAL7PPD.js";
+import "./chunk-J47KPS77.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
@@ -33,7 +34,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-QWV7JDLQ.js";
+} from "./chunk-LHFNHB2J.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -52,6 +53,7 @@ export {
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
+  defineReplayRegistry,
   finalizers,
   flushTraces,
   getCurrentReplayBranch,

package/dist/node.cjs

@@ -97,7 +97,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.38.2";
+    __version__ = "0.38.4";
     __packageName__ = "bitfab";
   }
 });
@@ -2820,6 +2820,11 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       );
     }
   }
+  if (options?.traceIds !== void 0 && options?.datasetId !== void 0) {
+    throw new BitfabError(
+      "traceIds and datasetId select different replay sources and cannot be used together."
+    );
+  }
   if (options?.limit !== void 0 && options?.traceIds !== void 0) {
     try {
       console.warn(
@@ -3147,6 +3152,7 @@ __export(node_exports, {
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
+  defineReplayRegistry: () => defineReplayRegistry,
   finalizers: () => finalizers,
   flushTraces: () => flushTraces,
   getCurrentReplayBranch: () => getCurrentReplayBranch,
@@ -3805,6 +3811,29 @@ function runWithAutoTraceContext(context, fn, depth = 0) {
     autoTraceState.browserScope = previous;
   }
 }
+function runWithAutoTraceNodeConfiguration(nodeConfiguration, fn) {
+  const scope = currentAutoTraceScope();
+  if (!scope) {
+    return fn();
+  }
+  const configuredScope = { ...scope, nodeConfiguration };
+  let result;
+  if (autoTraceState.storage) {
+    result = autoTraceState.storage.run(configuredScope, fn);
+  } else {
+    const previous = autoTraceState.browserScope;
+    autoTraceState.browserScope = configuredScope;
+    try {
+      result = fn();
+    } finally {
+      autoTraceState.browserScope = previous;
+    }
+  }
+  if (isAutoTraceAsyncGenerator(result)) {
+    return wrapAutoTraceNodeAsyncGenerator(nodeConfiguration, result);
+  }
+  return result;
+}
 function runWithAutoTraceRootContext(context, fn) {
   autoTraceState.activeRoots += 1;
   let result;
@@ -3843,6 +3872,29 @@ function wrapAutoTraceAsyncGenerator(context, source) {
   };
   return wrapped;
 }
+function wrapAutoTraceNodeAsyncGenerator(nodeConfiguration, source) {
+  const step = (method, value) => runWithAutoTraceNodeConfiguration(
+    nodeConfiguration,
+    () => source[method](value)
+  );
+  const wrapped = {
+    next: (value) => step("next", value),
+    return: (value) => step("return", value),
+    throw: (error) => step("throw", error),
+    [Symbol.asyncIterator]: () => wrapped
+  };
+  return wrapped;
+}
+function __bitfabAutoTraceActive() {
+  if (autoTraceState.activeRoots === 0) {
+    return false;
+  }
+  return currentAutoTraceScope() !== void 0;
+}
+function currentAutoTraceScope() {
+  initializeAutoTraceStorage();
+  return autoTraceState.storage?.getStore() ?? autoTraceState.browserScope;
+}
 function __setBitfabAutoTraceCapturePolicy(client, traceFunctionKey, functionIds) {
   const policies = autoTraceState.capturePolicies.get(client) ?? /* @__PURE__ */ new Map();
   policies.set(traceFunctionKey, new Set(functionIds));
@@ -5695,6 +5747,102 @@ var Bitfab = class {
     const name = fn.name !== "" ? fn.name : traceFunctionKey;
     return this.createAutoTraceRoot(traceFunctionKey, name, options, fn);
   }
+  /**
+   * Configure a transformed class method when it is discovered beneath a
+   * {@link Bitfab.trace} root.
+   *
+   * The decorator creates no span or trace by itself. Beneath an active trace,
+   * it can rename or retype the discovered call, capture its contents, mark it
+   * for recorded-output replay, finalize its output, or omit it while leaving
+   * captured descendants attached to the nearest captured parent.
+   *
+   * @param options - Trace-owned call configuration.
+   * @experimental Automatic child-call instrumentation is experimental.
+   */
+  node(options = {}) {
+    const configuration = this.resolveNodeConfiguration(options);
+    const decorator = (...args) => {
+      if (args.length === 3) {
+        const descriptor = args[2];
+        if (!descriptor || typeof descriptor.value !== "function") {
+          throw new BitfabError("@bitfab.node can only decorate methods");
+        }
+        if (!this.explicitlyEnabled) {
+          return;
+        }
+        descriptor.value = this.createAutoTraceNode(
+          configuration,
+          descriptor.value,
+          String(args[1])
+        );
+        return;
+      }
+      const method = args[0];
+      const context = args[1];
+      if (typeof method !== "function" || context?.kind !== "method") {
+        throw new BitfabError("@bitfab.node can only decorate methods");
+      }
+      if (!this.explicitlyEnabled) {
+        return method;
+      }
+      return this.createAutoTraceNode(
+        configuration,
+        method,
+        String(context.name)
+      );
+    };
+    return decorator;
+  }
+  withNode(optionsOrFn, maybeFn, internalFunctionName) {
+    const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
+    const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+    if (!fn) {
+      throw new BitfabError("bitfab.withNode requires a function");
+    }
+    const configuration = this.resolveNodeConfiguration(options);
+    if (!this.explicitlyEnabled) {
+      return fn;
+    }
+    const functionName = internalFunctionName ?? fn.name;
+    if (functionName === "") {
+      throw new BitfabError(
+        "bitfab.withNode requires a named function so the subtree transform can bind its configuration to the correct call."
+      );
+    }
+    return this.createAutoTraceNode(configuration, fn, functionName);
+  }
+  resolveNodeConfiguration(options) {
+    const capture = options.capture ?? true;
+    if (!capture && options.mockOnReplay === true) {
+      throw new BitfabError(
+        "bitfab.node({ capture: false }) cannot use mockOnReplay: true because an uncaptured node has no recorded output."
+      );
+    }
+    return {
+      capture,
+      type: options.type ?? "custom",
+      ...options.name !== void 0 && { name: options.name },
+      ...options.testRunId !== void 0 && {
+        testRunId: options.testRunId
+      },
+      ...options.mockOnReplay !== void 0 && {
+        mockOnReplay: options.mockOnReplay
+      },
+      ...options.finalize !== void 0 && { finalize: options.finalize }
+    };
+  }
+  createAutoTraceNode(configuration, fn, functionName) {
+    const nodeConfiguration = { ...configuration, functionName };
+    return function(...args) {
+      if (!__bitfabAutoTraceActive()) {
+        return fn.apply(this, args);
+      }
+      return runWithAutoTraceNodeConfiguration(
+        nodeConfiguration,
+        () => fn.apply(this, args)
+      );
+    };
+  }
   createAutoTraceRoot(traceFunctionKey, name, options, fn) {
     const self = this;
     const maxDepth = autoTraceLimit(
@@ -5733,29 +5881,51 @@ var Bitfab = class {
           );
         };
         const autoTraceContext = {
-          invoke(definition, inputs, invokeFn, depth) {
+          invoke(definition, inputs, invokeFn, depth, nodeConfiguration) {
             const nameParts = definition.name.split(".");
             const simpleName = nameParts[nameParts.length - 1];
-            if (excluded.has(definition.name) || simpleName !== void 0 && excluded.has(simpleName) || definition.wrapper === true && !includeWrappers) {
-              return invokeFn();
+            const invokeWithoutNode = () => nodeConfiguration === void 0 ? invokeFn() : runWithAutoTraceContext(autoTraceContext, invokeFn, depth);
+            if (excluded.has(definition.name) || simpleName !== void 0 && excluded.has(simpleName) || nodeConfiguration === void 0 && definition.wrapper === true && !includeWrappers) {
+              return invokeWithoutNode();
+            }
+            if (nodeConfiguration?.capture === false) {
+              return runWithAutoTraceContext(autoTraceContext, invokeFn, depth);
             }
             if (depth >= maxDepth || spansUsed >= maxSpans) {
               warnTruncated();
-              return invokeFn();
+              return invokeWithoutNode();
             }
             spansUsed += 1;
             const childOptions = {
-              name: definition.name,
-              type: "function",
+              name: nodeConfiguration?.name ?? definition.name,
+              type: nodeConfiguration?.type ?? "function",
               captureWhen: "nested",
               functionId: definition.id,
-              captureContent: capturePolicy.has(definition.id),
-              autoTraceDefinition: definition
+              captureContent: nodeConfiguration !== void 0 || capturePolicy.has(definition.id),
+              autoTraceDefinition: definition,
+              ...nodeConfiguration?.testRunId !== void 0 && {
+                testRunId: nodeConfiguration.testRunId
+              },
+              ...nodeConfiguration?.mockOnReplay !== void 0 && {
+                mockOnReplay: nodeConfiguration.mockOnReplay
+              },
+              ...nodeConfiguration?.finalize !== void 0 && {
+                finalize: nodeConfiguration.finalize
+              }
             };
+            const invokeWithAutoTraceContext = () => runWithAutoTraceContext(autoTraceContext, invokeFn, depth + 1);
+            if (definition.async === true) {
+              const tracedAsyncChild = self.withSpan(
+                traceFunctionKey,
+                childOptions,
+                async (..._inputs) => await invokeWithAutoTraceContext()
+              );
+              return tracedAsyncChild(...inputs);
+            }
             const tracedChild = self.withSpan(
               traceFunctionKey,
               childOptions,
-              (..._inputs) => runWithAutoTraceContext(autoTraceContext, invokeFn, depth + 1)
+              (..._inputs) => invokeWithAutoTraceContext()
             );
             return tracedChild(...inputs);
           }
@@ -6325,18 +6495,17 @@ var Bitfab = class {
         newStack = [...currentStack, newContext];
         const inputs = args;
         const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+        const replayCtxAtStart = getReplayContext();
+        const testRunId = replayCtxAtStart?.testRunId ?? options.testRunId;
         if (isRootSpan && !activeTraceStates.has(traceId)) {
-          const replayCtxAtRoot = getReplayContext();
           const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
           activeTraceStates.set(traceId, {
             traceId,
             startedAt,
             contexts: [],
-            ...replayCtxAtRoot?.testRunId && {
-              testRunId: replayCtxAtRoot.testRunId
-            },
-            ...replayCtxAtRoot?.inputSourceTraceId && {
-              inputSourceTraceId: replayCtxAtRoot.inputSourceTraceId
+            ...testRunId !== void 0 && { testRunId },
+            ...replayCtxAtStart?.inputSourceTraceId && {
+              inputSourceTraceId: replayCtxAtStart.inputSourceTraceId
             },
             dbSnapshotRef
           });
@@ -6369,9 +6538,7 @@ var Bitfab = class {
                 contexts: newContext.contexts,
                 prompt: newContext.prompt,
                 endedAt,
-                ...replayCtx?.testRunId && {
-                  testRunId: replayCtx.testRunId
-                },
+                ...testRunId !== void 0 && { testRunId },
                 ...replayCtx?.inputSourceSpanId && {
                   inputSourceSpanId: replayCtx.inputSourceSpanId
                 }
@@ -7087,6 +7254,13 @@ var finalizers = {
 init_http();
 init_replay();
 
+// src/replayRegistry.ts
+init_errors();
+init_replay();
+function defineReplayRegistry(registry) {
+  return registry;
+}
+
 // src/node.ts
 init_asyncStorage();
 assertAsyncStorageRegistered();
@@ -7108,6 +7282,7 @@ assertAsyncStorageRegistered();
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
+  defineReplayRegistry,
   finalizers,
   flushTraces,
   getCurrentReplayBranch,