@bitfab/sdk 0.38.4 → 0.38.6

package/dist/index.d.cts

@@ -147,10 +147,23 @@ interface MockOverrideCtx {
      */
     getOriginalOutput: () => Promise<unknown>;
 }
+/**
+ * Return this from a mock override resolver to decline the override for the
+ * current span. Resolution continues with the next override, then the replay's
+ * base mock strategy.
+ */
+declare const NO_MOCK_OVERRIDE: unique symbol;
 /** Selects which spans an override applies to. Runs on structural metadata. */
 type NodeMatcher = (node: SpanNodeMeta) => boolean;
 /** The function form of {@link MockValue}, receiving the override context. */
 type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
+/**
+ * A client-wide, keyed, or per-replay resolver. A global resolver can route on
+ * `ctx.node.traceFunctionKey`; a keyed resolver is only invoked for spans with
+ * its registered key. Return {@link NO_MOCK_OVERRIDE} for spans the resolver
+ * does not want to override.
+ */
+type MockOverrideResolver = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
 /**
  * The value injected for a matched span: either a flat value used as-is, or a
  * function of the {@link MockOverrideCtx} that returns one (or a Promise of
@@ -168,6 +181,8 @@ interface MockOverride {
     match: NodeMatcher;
     value: MockValue;
 }
+/** Accepted shape for one mock override declaration. */
+type MockOverrideInput = MockOverride | MockOverrideResolver;
 
 /**
  * Replay context propagation via AsyncLocalStorage.
@@ -1268,12 +1283,12 @@ interface ReplayOptions {
     /**
      * Selective mock overrides: inject custom values into specific spans during
      * replay, so downstream real code runs against the substituted output. Each
-     * override is a `{ match, value }` pair; the first matcher that
-     * matches a span wins. These take precedence over any overrides registered on
-     * the client via `registerMockOverride`, and over the base `mock` strategy - a
-     * span no override matches falls back to that strategy. See {@link MockOverride}.
+     * Pass `{ match, value }` pairs, or one resolver invoked for every child span.
+     * A resolver can route on `ctx.node.traceFunctionKey` and return
+     * `NO_MOCK_OVERRIDE` to continue to the next override and base strategy.
+     * Per-call overrides take precedence over registrations on the client.
      */
-    mockOverride?: MockOverride | MockOverride[];
+    mockOverride?: MockOverrideInput | MockOverrideInput[];
     /**
      * Run each item against a database branch restored to the state its source
      * trace saw. Pass `true` to branch with the mirror project's own sizing, or a
@@ -2168,8 +2183,9 @@ declare class Bitfab {
      * Decorate a class method as an automatically expanded trace root.
      *
      * Build instrumentation turns repository functions called beneath this
-     * method into nested spans. Every generated span preserves structure; only
-     * function IDs selected by the capture policy include inputs and output.
+     * method into nested spans that capture inputs, outputs, and errors by
+     * default. A confirmed capture policy can narrow rich capture to selected
+     * function IDs.
      * Without a compatible build transform, this still records the decorated
      * method as a normal rich root span but cannot discover child calls.
      *
@@ -2183,8 +2199,10 @@ declare class Bitfab {
      *
      * This is the function-oriented equivalent of {@link Bitfab.trace}. Build
      * instrumentation turns repository functions called beneath the wrapped
-     * function into nested spans. Without a compatible transform, this still
-     * records one normal rich root span and runs the function unchanged.
+     * function into nested spans that capture inputs, outputs, and errors by
+     * default. A confirmed capture policy can narrow rich capture to selected
+     * function IDs. Without a compatible transform, this still records one
+     * normal rich root span and runs the function unchanged.
      *
      * @param traceFunctionKey - Groups traces and their capture policy.
      * @param optionsOrFn - Options or the workflow entrypoint to wrap.
@@ -2584,10 +2602,22 @@ declare class Bitfab {
      *   (node) => node.traceFunctionKey === "classify-intent",
      *   ({ inputs }) => ({ label: "refund" }),
      * )
+     * // Keyed form: the resolver only sees spans for this trace function key.
+     * bitfab.registerMockOverride("classify-intent", ({ inputs }) => ({
+     *   label: String(inputs[0]),
+     * }))
+     * // Or one resolver for every child span:
+     * bitfab.registerMockOverride(({ node }) =>
+     *   node.traceFunctionKey === "classify-intent"
+     *     ? { label: "refund" }
+     *     : NO_MOCK_OVERRIDE,
+     * )
      * ```
      */
     registerMockOverride(override: MockOverride): void;
+    registerMockOverride(resolver: MockOverrideResolver): void;
     registerMockOverride(match: NodeMatcher, value: MockValue): void;
+    registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
     /** Remove all overrides registered via {@link registerMockOverride}. */
     clearMockOverrides(): void;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
@@ -2759,7 +2789,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.4";
+declare const __version__ = "0.38.6";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2862,4 +2892,4 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  */
 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 };
+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 MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, 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

@@ -147,10 +147,23 @@ interface MockOverrideCtx {
      */
     getOriginalOutput: () => Promise<unknown>;
 }
+/**
+ * Return this from a mock override resolver to decline the override for the
+ * current span. Resolution continues with the next override, then the replay's
+ * base mock strategy.
+ */
+declare const NO_MOCK_OVERRIDE: unique symbol;
 /** Selects which spans an override applies to. Runs on structural metadata. */
 type NodeMatcher = (node: SpanNodeMeta) => boolean;
 /** The function form of {@link MockValue}, receiving the override context. */
 type MockValueFn = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
+/**
+ * A client-wide, keyed, or per-replay resolver. A global resolver can route on
+ * `ctx.node.traceFunctionKey`; a keyed resolver is only invoked for spans with
+ * its registered key. Return {@link NO_MOCK_OVERRIDE} for spans the resolver
+ * does not want to override.
+ */
+type MockOverrideResolver = (ctx: MockOverrideCtx) => unknown | Promise<unknown>;
 /**
  * The value injected for a matched span: either a flat value used as-is, or a
  * function of the {@link MockOverrideCtx} that returns one (or a Promise of
@@ -168,6 +181,8 @@ interface MockOverride {
     match: NodeMatcher;
     value: MockValue;
 }
+/** Accepted shape for one mock override declaration. */
+type MockOverrideInput = MockOverride | MockOverrideResolver;
 
 /**
  * Replay context propagation via AsyncLocalStorage.
@@ -1268,12 +1283,12 @@ interface ReplayOptions {
     /**
      * Selective mock overrides: inject custom values into specific spans during
      * replay, so downstream real code runs against the substituted output. Each
-     * override is a `{ match, value }` pair; the first matcher that
-     * matches a span wins. These take precedence over any overrides registered on
-     * the client via `registerMockOverride`, and over the base `mock` strategy - a
-     * span no override matches falls back to that strategy. See {@link MockOverride}.
+     * Pass `{ match, value }` pairs, or one resolver invoked for every child span.
+     * A resolver can route on `ctx.node.traceFunctionKey` and return
+     * `NO_MOCK_OVERRIDE` to continue to the next override and base strategy.
+     * Per-call overrides take precedence over registrations on the client.
      */
-    mockOverride?: MockOverride | MockOverride[];
+    mockOverride?: MockOverrideInput | MockOverrideInput[];
     /**
      * Run each item against a database branch restored to the state its source
      * trace saw. Pass `true` to branch with the mirror project's own sizing, or a
@@ -2168,8 +2183,9 @@ declare class Bitfab {
      * Decorate a class method as an automatically expanded trace root.
      *
      * Build instrumentation turns repository functions called beneath this
-     * method into nested spans. Every generated span preserves structure; only
-     * function IDs selected by the capture policy include inputs and output.
+     * method into nested spans that capture inputs, outputs, and errors by
+     * default. A confirmed capture policy can narrow rich capture to selected
+     * function IDs.
      * Without a compatible build transform, this still records the decorated
      * method as a normal rich root span but cannot discover child calls.
      *
@@ -2183,8 +2199,10 @@ declare class Bitfab {
      *
      * This is the function-oriented equivalent of {@link Bitfab.trace}. Build
      * instrumentation turns repository functions called beneath the wrapped
-     * function into nested spans. Without a compatible transform, this still
-     * records one normal rich root span and runs the function unchanged.
+     * function into nested spans that capture inputs, outputs, and errors by
+     * default. A confirmed capture policy can narrow rich capture to selected
+     * function IDs. Without a compatible transform, this still records one
+     * normal rich root span and runs the function unchanged.
      *
      * @param traceFunctionKey - Groups traces and their capture policy.
      * @param optionsOrFn - Options or the workflow entrypoint to wrap.
@@ -2584,10 +2602,22 @@ declare class Bitfab {
      *   (node) => node.traceFunctionKey === "classify-intent",
      *   ({ inputs }) => ({ label: "refund" }),
      * )
+     * // Keyed form: the resolver only sees spans for this trace function key.
+     * bitfab.registerMockOverride("classify-intent", ({ inputs }) => ({
+     *   label: String(inputs[0]),
+     * }))
+     * // Or one resolver for every child span:
+     * bitfab.registerMockOverride(({ node }) =>
+     *   node.traceFunctionKey === "classify-intent"
+     *     ? { label: "refund" }
+     *     : NO_MOCK_OVERRIDE,
+     * )
      * ```
      */
     registerMockOverride(override: MockOverride): void;
+    registerMockOverride(resolver: MockOverrideResolver): void;
     registerMockOverride(match: NodeMatcher, value: MockValue): void;
+    registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
     /** Remove all overrides registered via {@link registerMockOverride}. */
     clearMockOverrides(): void;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
@@ -2759,7 +2789,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.4";
+declare const __version__ = "0.38.6";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2862,4 +2892,4 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  */
 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 };
+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 MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, 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

@@ -12,20 +12,21 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-NKX3EY35.js";
-import "./chunk-J47KPS77.js";
+} from "./chunk-P2MYK27A.js";
+import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   DEFAULT_SERVICE_URL,
   DbBranchReplayError,
   HttpClient,
+  NO_MOCK_OVERRIDE,
   ReplayError,
   __version__,
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-5GWBJGYZ.js";
+} from "./chunk-QTTKZMHM.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -41,6 +42,7 @@ export {
   DEFAULT_SERVICE_URL,
   DbBranchReplayError,
   HttpClient,
+  NO_MOCK_OVERRIDE,
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.38.4";
+    __version__ = "0.38.6";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2194,11 +2194,16 @@ function normalizeMockOverrides(mockOverride) {
   if (mockOverride === void 0) {
     return [];
   }
-  return Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+  const overrides = Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+  return overrides.map(
+    (override) => typeof override === "function" ? { match: () => true, value: override } : override
+  );
 }
+var NO_MOCK_OVERRIDE;
 var init_mockOverride = __esm({
   "src/mockOverride.ts"() {
     "use strict";
+    NO_MOCK_OVERRIDE = /* @__PURE__ */ Symbol("bitfab.noMockOverride");
   }
 });
 
@@ -3140,6 +3145,7 @@ __export(node_exports, {
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
   DbBranchReplayError: () => DbBranchReplayError,
   HttpClient: () => HttpClient,
+  NO_MOCK_OVERRIDE: () => NO_MOCK_OVERRIDE,
   ReplayError: () => ReplayError,
   SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
   __version__: () => __version__,
@@ -3888,11 +3894,18 @@ function currentAutoTraceScope() {
 }
 function __setBitfabAutoTraceCapturePolicy(client, traceFunctionKey, functionIds) {
   const policies = autoTraceState.capturePolicies.get(client) ?? /* @__PURE__ */ new Map();
+  if (functionIds === void 0) {
+    policies.delete(traceFunctionKey);
+    if (policies.size === 0) {
+      autoTraceState.capturePolicies.delete(client);
+    }
+    return;
+  }
   policies.set(traceFunctionKey, new Set(functionIds));
   autoTraceState.capturePolicies.set(client, policies);
 }
 function getAutoTraceCapturePolicy(client, traceFunctionKey) {
-  return autoTraceState.capturePolicies.get(client)?.get(traceFunctionKey) ?? /* @__PURE__ */ new Set();
+  return autoTraceState.capturePolicies.get(client)?.get(traceFunctionKey);
 }
 
 // src/optionalPeer.ts
@@ -5681,8 +5694,9 @@ var Bitfab = class {
    * Decorate a class method as an automatically expanded trace root.
    *
    * Build instrumentation turns repository functions called beneath this
-   * method into nested spans. Every generated span preserves structure; only
-   * function IDs selected by the capture policy include inputs and output.
+   * method into nested spans that capture inputs, outputs, and errors by
+   * default. A confirmed capture policy can narrow rich capture to selected
+   * function IDs.
    * Without a compatible build transform, this still records the decorated
    * method as a normal rich root span but cannot discover child calls.
    *
@@ -5892,7 +5906,7 @@ var Bitfab = class {
               type: nodeConfiguration?.type ?? "function",
               captureWhen: "nested",
               functionId: definition.id,
-              captureContent: nodeConfiguration !== void 0 || capturePolicy.has(definition.id),
+              captureContent: nodeConfiguration !== void 0 || capturePolicy === void 0 || capturePolicy.has(definition.id),
               autoTraceDefinition: definition,
               ...nodeConfiguration?.testRunId !== void 0 && {
                 testRunId: nodeConfiguration.testRunId
@@ -5957,7 +5971,11 @@ var Bitfab = class {
       const functionIds = Array.isArray(policy.functionIds) ? policy.functionIds.filter(
         (id) => typeof id === "string" && id.startsWith(`${AUTO_TRACE_PROTOCOL}:`)
       ).slice(0, DEFAULT_AUTO_TRACE_MAX_SPANS) : [];
-      __setBitfabAutoTraceCapturePolicy(this, traceFunctionKey, functionIds);
+      __setBitfabAutoTraceCapturePolicy(
+        this,
+        traceFunctionKey,
+        policy.revision === null ? void 0 : functionIds
+      );
       state.refreshAfter = Date.now() + AUTO_TRACE_POLICY_REFRESH_MS;
     }).catch(() => {
       state.refreshAfter = Date.now() + AUTO_TRACE_POLICY_RETRY_MS;
@@ -6569,6 +6587,49 @@ var Bitfab = class {
           } catch {
           }
         };
+        const recordSpan = (result) => {
+          if (options.finalize) {
+            void self.httpClient.trackDeferred(
+              Promise.resolve().then(() => options.finalize(result)).then((output) => sendSpan({ result: output })).catch(
+                (error) => sendSpan({
+                  result: void 0,
+                  error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
+                })
+              )
+            );
+          } else {
+            void sendSpan({ result });
+          }
+        };
+        executeWithContext = () => {
+          let result;
+          try {
+            result = fn.apply(this, args);
+          } catch (error) {
+            void sendSpan({
+              result: void 0,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+          }
+          if (result instanceof Promise) {
+            return result.then((resolvedResult) => {
+              recordSpan(resolvedResult);
+              return resolvedResult;
+            }).catch((error) => {
+              void sendSpan({
+                result: void 0,
+                error: error instanceof Error ? error.message : String(error)
+              });
+              throw error;
+            });
+          }
+          if (isAsyncGenerator(result)) {
+            return wrapAsyncGenerator(result, newStack, sendSpan);
+          }
+          recordSpan(result);
+          return result;
+        };
         const replayCtxForMock = getReplayContext();
         if (replayCtxForMock?.mockTree && !isRootSpan) {
           const counters = replayCtxForMock.callCounters;
@@ -6627,6 +6688,7 @@ var Bitfab = class {
             }
             return output;
           };
+          const shouldMockWithBaseStrategy = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
           if (replayCtxForMock.mockOverrides?.length) {
             const nodeMeta = {
               traceFunctionKey,
@@ -6634,28 +6696,75 @@ var Bitfab = class {
               type: options.type ?? "custom",
               originalSpanId: mockSpan?.sourceSpanId
             };
-            const override = replayCtxForMock.mockOverrides.find(
-              (o) => o.match(nodeMeta)
-            );
-            if (override) {
-              const injected = resolveMockValue(override.value, {
-                node: nodeMeta,
-                inputs: args,
-                getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
-              });
-              if (injected instanceof Promise) {
-                return emitMockAsync(injected, "override");
+            const overrideCtx = {
+              node: nodeMeta,
+              inputs: args,
+              getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
+            };
+            const resolveOverrideFrom = (startIndex) => {
+              for (let index = startIndex; index < replayCtxForMock.mockOverrides.length; index += 1) {
+                const override = replayCtxForMock.mockOverrides[index];
+                if (!override?.match(nodeMeta)) {
+                  continue;
+                }
+                const injected = resolveMockValue(override.value, overrideCtx);
+                if (injected instanceof Promise) {
+                  return injected.then(
+                    (output) => output === NO_MOCK_OVERRIDE ? resolveOverrideFrom(index + 1) : { matched: true, output }
+                  );
+                }
+                if (injected !== NO_MOCK_OVERRIDE) {
+                  return { matched: true, output: injected };
+                }
               }
-              return emitMock(injected, "override");
+              return { matched: false };
+            };
+            const resolution = resolveOverrideFrom(0);
+            if (resolution instanceof Promise) {
+              if (!fnReturnsPromise) {
+                throw new BitfabError(
+                  `Cannot resolve an asynchronous mock override for synchronous span "${traceFunctionKey}". Make the wrapped function async or return NO_MOCK_OVERRIDE synchronously.`
+                );
+              }
+              return runWithSpanStack(newStack, async () => {
+                const resolved = await resolution;
+                if (resolved.matched) {
+                  void sendSpan({
+                    result: resolved.output,
+                    mocked: true,
+                    mockTarget: "output",
+                    mockSource: "override"
+                  });
+                  return resolved.output;
+                }
+                if (shouldMockWithBaseStrategy && !mockSpan) {
+                  throw new BitfabError(
+                    `Replay selected span "${traceFunctionKey}:${baseSpanParams.spanName}" for mocking, but recorded occurrence ${callIndex + 1} is unavailable. The real span was not executed.`
+                  );
+                }
+                if (shouldMockWithBaseStrategy) {
+                  const output = await resolveRecordedOutput();
+                  void sendSpan({
+                    result: output,
+                    mocked: true,
+                    mockTarget: "output",
+                    mockSource: "recorded"
+                  });
+                  return output;
+                }
+                return executeWithContext();
+              });
+            }
+            if (resolution.matched) {
+              return emitMock(resolution.output, "override");
             }
           }
-          const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
-          if (shouldMock && !mockSpan) {
+          if (shouldMockWithBaseStrategy && !mockSpan) {
             throw new BitfabError(
               `Replay selected span "${traceFunctionKey}:${baseSpanParams.spanName}" for mocking, but recorded occurrence ${callIndex + 1} is unavailable. The real span was not executed.`
             );
           }
-          if (shouldMock) {
+          if (shouldMockWithBaseStrategy) {
             const recorded = resolveRecordedOutput();
             if (recorded instanceof Promise) {
               return emitMockAsync(recorded, "recorded");
@@ -6663,49 +6772,6 @@ var Bitfab = class {
             return emitMock(recorded, "recorded");
           }
         }
-        const recordSpan = (result) => {
-          if (options.finalize) {
-            void self.httpClient.trackDeferred(
-              Promise.resolve().then(() => options.finalize(result)).then((output) => sendSpan({ result: output })).catch(
-                (error) => sendSpan({
-                  result: void 0,
-                  error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
-                })
-              )
-            );
-          } else {
-            void sendSpan({ result });
-          }
-        };
-        executeWithContext = () => {
-          let result;
-          try {
-            result = fn.apply(this, args);
-          } catch (error) {
-            void sendSpan({
-              result: void 0,
-              error: error instanceof Error ? error.message : String(error)
-            });
-            throw error;
-          }
-          if (result instanceof Promise) {
-            return result.then((resolvedResult) => {
-              recordSpan(resolvedResult);
-              return resolvedResult;
-            }).catch((error) => {
-              void sendSpan({
-                result: void 0,
-                error: error instanceof Error ? error.message : String(error)
-              });
-              throw error;
-            });
-          }
-          if (isAsyncGenerator(result)) {
-            return wrapAsyncGenerator(result, newStack, sendSpan);
-          }
-          recordSpan(result);
-          return result;
-        };
       } catch (setupError) {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
@@ -6992,8 +7058,40 @@ var Bitfab = class {
       ...params.mockSource && { mockSource: params.mockSource }
     });
   }
-  registerMockOverride(overrideOrMatch, value) {
-    const override = typeof overrideOrMatch === "function" ? { match: overrideOrMatch, value } : overrideOrMatch;
+  registerMockOverride(overrideOrResolverOrMatch, ...values) {
+    let override;
+    if (typeof overrideOrResolverOrMatch === "string") {
+      const keyedOverride = values[0];
+      if (values.length !== 1 || keyedOverride === void 0) {
+        throw new BitfabError(
+          "registerMockOverride(traceFunctionKey, override) requires a resolver function or { match, value } override."
+        );
+      }
+      if (typeof keyedOverride === "function") {
+        override = {
+          match: (node) => node.traceFunctionKey === overrideOrResolverOrMatch,
+          value: keyedOverride
+        };
+      } else if (typeof keyedOverride === "object" && keyedOverride !== null && "match" in keyedOverride && "value" in keyedOverride) {
+        override = {
+          match: (node) => node.traceFunctionKey === overrideOrResolverOrMatch && keyedOverride.match(node),
+          value: keyedOverride.value
+        };
+      } else {
+        throw new BitfabError(
+          "registerMockOverride(traceFunctionKey, override) requires a resolver function or { match, value } override."
+        );
+      }
+    } else if (typeof overrideOrResolverOrMatch !== "function") {
+      override = overrideOrResolverOrMatch;
+    } else if (values.length === 0) {
+      override = { match: () => true, value: overrideOrResolverOrMatch };
+    } else {
+      override = {
+        match: overrideOrResolverOrMatch,
+        value: values[0]
+      };
+    }
     this.mockOverrides.push(override);
   }
   /** Remove all overrides registered via {@link registerMockOverride}. */
@@ -7243,6 +7341,7 @@ var finalizers = {
 
 // src/index.ts
 init_http();
+init_mockOverride();
 init_replay();
 
 // src/replayRegistry.ts
@@ -7270,6 +7369,7 @@ assertAsyncStorageRegistered();
   DEFAULT_SERVICE_URL,
   DbBranchReplayError,
   HttpClient,
+  NO_MOCK_OVERRIDE,
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,