@bitfab/sdk 0.43.1 → 0.44.1

package/dist/index.d.cts

@@ -98,6 +98,9 @@ declare class BitfabError extends Error {
      */
     retryAfterMs?: number | undefined);
 }
+declare class MixedTracingError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Selective mock overrides for replay.
@@ -644,6 +647,32 @@ interface TokenUsage {
     cached: number | null;
     total: number | null;
 }
+interface TraceOutlineSpanError {
+    source: string;
+    error: string;
+    step?: string;
+}
+interface TraceOutlineSpan {
+    spanId: string;
+    name: string | null;
+    type: string;
+    traceFunctionKey: string | null;
+    durationMs: number | null;
+    tokens: TokenUsage | null;
+    model: string | null;
+    errors: TraceOutlineSpanError[] | null;
+    mocked: boolean;
+    children: TraceOutlineSpan[];
+}
+interface TraceOutline {
+    traceId: string;
+    name: string | null;
+    status: string;
+    traceFunctionKey: string | null;
+    durationMs: number | null;
+    spanCount: number;
+    spans: TraceOutlineSpan[];
+}
 /**
  * Describes a single file edited as part of a code change.
  *
@@ -743,6 +772,8 @@ interface CompleteReplayResponse {
      * `ReplayItem.tokens`. Absent on servers that predate this field.
      */
     tokens?: Record<string, TokenUsage | null>;
+    traceOutlines?: Record<string, TraceOutline>;
+    originalTraceOutlines?: Record<string, TraceOutline>;
     /**
      * Number of traces the server has persisted for this test run at
      * completion time. Lets the SDK distinguish "uploads failed" from
@@ -1690,6 +1721,8 @@ interface ReplayProgressItem {
     model?: string | null;
     dbSnapshotRef?: DbSnapshotRef | null;
     dbBranchTimings?: DbBranchTimings | null;
+    traceOutline?: TraceOutline | null;
+    originalTraceOutline?: TraceOutline | null;
 }
 /**
  * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
@@ -1841,6 +1874,8 @@ interface ReplayItem<T> {
      * no snapshot ref, or against a server that predates timings.
      */
     dbBranchTimings: DbBranchTimings | null;
+    traceOutline: TraceOutline | null;
+    originalTraceOutline: TraceOutline | null;
 }
 
 interface ReplayResult<T> {
@@ -2096,6 +2131,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
 }
 
 type CaptureSurface = "opt-in" | "opt-out";
+
 /**
  * Options for wrapBAML.
  */
@@ -3078,7 +3114,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.43.1";
+declare const __version__ = "0.44.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -3208,4 +3244,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, HttpClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, 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, type RerunGradersOptions, type RerunGradersResult, SUPPORTED_PROVIDERS, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, HttpClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, 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, type RerunGradersOptions, type RerunGradersResult, SUPPORTED_PROVIDERS, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };

package/dist/index.d.ts

@@ -98,6 +98,9 @@ declare class BitfabError extends Error {
      */
     retryAfterMs?: number | undefined);
 }
+declare class MixedTracingError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Selective mock overrides for replay.
@@ -644,6 +647,32 @@ interface TokenUsage {
     cached: number | null;
     total: number | null;
 }
+interface TraceOutlineSpanError {
+    source: string;
+    error: string;
+    step?: string;
+}
+interface TraceOutlineSpan {
+    spanId: string;
+    name: string | null;
+    type: string;
+    traceFunctionKey: string | null;
+    durationMs: number | null;
+    tokens: TokenUsage | null;
+    model: string | null;
+    errors: TraceOutlineSpanError[] | null;
+    mocked: boolean;
+    children: TraceOutlineSpan[];
+}
+interface TraceOutline {
+    traceId: string;
+    name: string | null;
+    status: string;
+    traceFunctionKey: string | null;
+    durationMs: number | null;
+    spanCount: number;
+    spans: TraceOutlineSpan[];
+}
 /**
  * Describes a single file edited as part of a code change.
  *
@@ -743,6 +772,8 @@ interface CompleteReplayResponse {
      * `ReplayItem.tokens`. Absent on servers that predate this field.
      */
     tokens?: Record<string, TokenUsage | null>;
+    traceOutlines?: Record<string, TraceOutline>;
+    originalTraceOutlines?: Record<string, TraceOutline>;
     /**
      * Number of traces the server has persisted for this test run at
      * completion time. Lets the SDK distinguish "uploads failed" from
@@ -1690,6 +1721,8 @@ interface ReplayProgressItem {
     model?: string | null;
     dbSnapshotRef?: DbSnapshotRef | null;
     dbBranchTimings?: DbBranchTimings | null;
+    traceOutline?: TraceOutline | null;
+    originalTraceOutline?: TraceOutline | null;
 }
 /**
  * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
@@ -1841,6 +1874,8 @@ interface ReplayItem<T> {
      * no snapshot ref, or against a server that predates timings.
      */
     dbBranchTimings: DbBranchTimings | null;
+    traceOutline: TraceOutline | null;
+    originalTraceOutline: TraceOutline | null;
 }
 
 interface ReplayResult<T> {
@@ -2096,6 +2131,7 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
 }
 
 type CaptureSurface = "opt-in" | "opt-out";
+
 /**
  * Options for wrapBAML.
  */
@@ -3078,7 +3114,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.43.1";
+declare const __version__ = "0.44.1";
 
 /**
  * Constants for the Bitfab SDK.
@@ -3208,4 +3244,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, HttpClient, type LangGraphIntegrationOptions, type ListDatasetsParams, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, 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, type RerunGradersOptions, type RerunGradersResult, SUPPORTED_PROVIDERS, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, HttpClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, 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, type RerunGradersOptions, type RerunGradersResult, SUPPORTED_PROVIDERS, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   getCurrentSpan,
   getCurrentTrace,
   seedFromRegistry
-} from "./chunk-V4MRFSWK.js";
+} from "./chunk-RZF5XSM6.js";
 import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -24,14 +24,15 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-TNGKCPBP.js";
+} from "./chunk-SMWYCJH6.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   HttpClient,
+  MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-5LY4XOUY.js";
+} from "./chunk-XTX66R4I.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -49,6 +50,7 @@ export {
   DatasetsClient,
   DbBranchReplayError,
   HttpClient,
+  MixedTracingError,
   NO_MOCK_OVERRIDE,
   ReplayError,
   SUPPORTED_PROVIDERS,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.43.1";
+    __version__ = "0.44.1";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -210,7 +210,7 @@ var init_compress = __esm({
 });
 
 // src/errors.ts
-var BitfabError;
+var BitfabError, MixedTracingError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -223,6 +223,12 @@ var init_errors = __esm({
         this.name = "BitfabError";
       }
     };
+    MixedTracingError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "MixedTracingError";
+      }
+    };
   }
 });
 
@@ -2720,7 +2726,9 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         tokens: null,
         model: serverItem.originalModel ?? serverItem.model ?? null,
         dbSnapshotRef: dbSnapshotRef ?? null,
-        dbBranchTimings: dbBranchTimings ?? null
+        dbBranchTimings: dbBranchTimings ?? null,
+        traceOutline: null,
+        originalTraceOutline: null
       };
     }
     try {
@@ -2804,7 +2812,9 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     tokens: null,
     model: originalModel,
     dbSnapshotRef: dbSnapshotRef ?? null,
-    dbBranchTimings: dbBranchTimings ?? null
+    dbBranchTimings: dbBranchTimings ?? null,
+    traceOutline: null,
+    originalTraceOutline: null
   };
 }
 async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds) {
@@ -3059,7 +3069,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             tokens: item.tokens,
             model: item.model,
             dbSnapshotRef: item.dbSnapshotRef,
-            dbBranchTimings: item.dbBranchTimings
+            dbBranchTimings: item.dbBranchTimings,
+            traceOutline: item.traceOutline,
+            originalTraceOutline: item.originalTraceOutline
           }
         });
       } catch {
@@ -3139,7 +3151,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
       if (mapped !== void 0) {
         item.tokens = replayTokens?.[mapped] ?? null;
+        item.traceOutline = completeResult.traceOutlines?.[mapped] ?? null;
       }
+      item.originalTraceOutline = completeResult.originalTraceOutlines?.[item.originalTraceId] ?? null;
     }
     if (completedCount > 0 && missing.length === completedCount) {
       const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
@@ -3262,6 +3276,7 @@ __export(node_exports, {
   DatasetsClient: () => DatasetsClient,
   DbBranchReplayError: () => DbBranchReplayError,
   HttpClient: () => HttpClient,
+  MixedTracingError: () => MixedTracingError,
   NO_MOCK_OVERRIDE: () => NO_MOCK_OVERRIDE,
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
@@ -4342,6 +4357,50 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
   };
 }
 
+// src/captureSurface.ts
+init_errors();
+var DEFAULT_SURFACE = "opt-in";
+var SURFACE_API = {
+  "opt-in": "withSpan()",
+  "opt-out": "withTrace()"
+};
+var MIXED_SURFACE_REMEDY = {
+  "opt-in": "Inside a withTrace/trace subtree, configure a discovered call with node()/withNode() instead, or trace this workflow with withSpan() only.",
+  "opt-out": "Wrap the caller with withTrace()/trace() as well, or wrap this function with withSpan()."
+};
+function resolveSurface(requested, parentSurface) {
+  if (requested === "neutral") {
+    return void 0;
+  }
+  if (requested === "inherit") {
+    return parentSurface ?? DEFAULT_SURFACE;
+  }
+  return requested;
+}
+function mixedTracingError(enteredApi, entered, enclosing, traceFunctionKey) {
+  const subject = traceFunctionKey === void 0 ? "" : ` for "${traceFunctionKey}"`;
+  return new MixedTracingError(
+    `opt-in and opt-out tracing can't be mixed in one call stack: ${enteredApi} (${entered})${subject} was entered inside a ${SURFACE_API[enclosing]} call (${enclosing}). ${MIXED_SURFACE_REMEDY[entered]}`
+  );
+}
+function assertSurfacesCompatible(requested, resolved, parentSurface, traceFunctionKey) {
+  if (requested === "inherit" || requested === "neutral") {
+    return;
+  }
+  if (resolved === void 0 || parentSurface === void 0) {
+    return;
+  }
+  if (parentSurface === resolved) {
+    return;
+  }
+  throw mixedTracingError(
+    SURFACE_API[resolved],
+    resolved,
+    parentSurface,
+    traceFunctionKey
+  );
+}
+
 // src/client.ts
 init_constants();
 
@@ -4488,6 +4547,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
 }
 
 // src/client.ts
+init_errors();
 init_http();
 
 // src/langgraph.ts
@@ -5877,18 +5937,6 @@ var BitfabVercelAiHandler = class {
 
 // src/client.ts
 init_warnOnce();
-var MIXED_SURFACE_REMEDY = {
-  "opt-in": "Inside a withTrace/trace subtree, configure a discovered call with node()/withNode() instead, or trace this workflow with withSpan() only.",
-  "opt-out": "Wrap the caller with withTrace()/trace() as well, or wrap this function with withSpan()."
-};
-function warnMixedTracingSurfaces(traceFunctionKey, entered, enclosing) {
-  const enteredApi = entered === "opt-in" ? "withSpan()" : "withTrace()";
-  const enclosingApi = enclosing === "opt-in" ? "withSpan()" : "withTrace()";
-  warnOnce(
-    `mixed-tracing-surface:${traceFunctionKey}:${entered}`,
-    `opt-in and opt-out tracing are mixed in one call stack: ${enteredApi} (${entered}) for "${traceFunctionKey}" was entered inside a ${enclosingApi} call (${enclosing}). Both are recorded, and the spans nest as written. ${MIXED_SURFACE_REMEDY[entered]}`
-  );
-}
 var activeTraceStates = /* @__PURE__ */ new Map();
 var asyncLocalStorage = null;
 var SPAN_CONTEXT_STORAGE_SYMBOL = /* @__PURE__ */ Symbol.for("bitfab.spanContextStorage");
@@ -5918,6 +5966,10 @@ function getSpanStack() {
   }
   return browserSpanStack;
 }
+function enclosingSurface() {
+  const stack = getSpanStack();
+  return stack[stack.length - 1]?.surface;
+}
 function runWithSpanStack(stack, fn) {
   if (asyncLocalStorage) {
     return asyncLocalStorage.run(stack, fn);
@@ -6404,6 +6456,9 @@ var Bitfab = class {
     const nodeConfiguration = { ...configuration, functionName };
     return function(...args) {
       if (!__bitfabAutoTraceActive()) {
+        if (enclosingSurface() === "opt-in") {
+          throw mixedTracingError("node()", "opt-out", "opt-in");
+        }
         return fn.apply(this, args);
       }
       return runWithAutoTraceNodeConfiguration(
@@ -7105,20 +7160,19 @@ var Bitfab = class {
         const spanId = randomUuid();
         const parentSpanId = parentContext?.spanId ?? null;
         const isRootSpan = parentSpanId === null;
-        const requestedSurface = options.surface ?? "opt-in";
-        const surface = requestedSurface === "inherit" ? parentContext?.surface ?? "opt-in" : requestedSurface;
-        if (requestedSurface !== "inherit" && parentContext?.surface !== void 0 && parentContext.surface !== surface) {
-          warnMixedTracingSurfaces(
-            traceFunctionKey,
-            surface,
-            parentContext.surface
-          );
-        }
+        const requestedSurface = options.surface ?? DEFAULT_SURFACE;
+        const surface = resolveSurface(requestedSurface, parentContext?.surface);
+        assertSurfacesCompatible(
+          requestedSurface,
+          surface,
+          parentContext?.surface,
+          traceFunctionKey
+        );
         const newContext = {
           traceId,
           spanId,
           contexts: [],
-          surface
+          ...surface !== void 0 && { surface }
         };
         newStack = [...currentStack, newContext];
         const inputs = args;
@@ -7401,6 +7455,9 @@ var Bitfab = class {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
         }
+        if (setupError instanceof MixedTracingError) {
+          throw setupError;
+        }
         if (getReplayContext() || inSeedScope()) {
           throw setupError;
         }
@@ -7800,9 +7857,14 @@ var Bitfab = class {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let target = fn;
     if (wrappedKey === void 0) {
+      const seedRootOptions = {
+        name: traceFunctionKey,
+        type: "agent",
+        surface: "neutral"
+      };
       target = this.withSpan(
         traceFunctionKey,
-        { name: traceFunctionKey, type: "agent" },
+        seedRootOptions,
         fn
       );
     } else if (wrappedKey !== traceFunctionKey) {
@@ -7844,11 +7906,12 @@ var Bitfab = class {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let replayFn = fn;
     if (wrappedKey === void 0) {
-      replayFn = this.withSpan(
-        traceFunctionKey,
-        { name: traceFunctionKey, type: "agent" },
-        fn
-      );
+      const replayRootOptions = {
+        name: traceFunctionKey,
+        type: "agent",
+        surface: "neutral"
+      };
+      replayFn = this.withSpan(traceFunctionKey, replayRootOptions, fn);
     } else if (wrappedKey !== traceFunctionKey) {
       throw new BitfabError(
         `Function is wrapped with trace function key '${wrappedKey}' but replay was called with '${traceFunctionKey}'. Pass matching keys, or pass the unwrapped function to replay it under the explicit key.`
@@ -8165,6 +8228,7 @@ assertAsyncStorageRegistered();
   DatasetsClient,
   DbBranchReplayError,
   HttpClient,
+  MixedTracingError,
   NO_MOCK_OVERRIDE,
   ReplayError,
   SUPPORTED_PROVIDERS,