@bitfab/sdk 0.36.11 → 0.36.13

package/dist/index.d.cts

@@ -182,8 +182,9 @@ interface MockOverride {
  * A single span entry in the mock tree.
  *
  * Under the eager path (`mock: "all"`) `output`/`outputMeta` are populated
- * inline. Under the lazy path (`marked` / overrides) they are absent and the
- * recorded output is fetched on demand via `externalSpanId` - see
+ * inline, even when overrides are present. Under a non-`all` path that needs a
+ * tree (`marked`, or `none` with overrides), they are absent and the recorded
+ * output is fetched on demand via `externalSpanId` - see
  * {@link ReplayContext.fetchSpanOutput}.
  */
 interface MockSpan {
@@ -267,9 +268,10 @@ interface ReplayContext {
     mockOverrides?: MockOverride[];
     /**
      * Memoized lazy fetch of a span's recorded output (deserialized), keyed by
-     * `externalSpanId`. Present ONLY on the lazy path (`marked` / overrides);
-     * absent under `mock: "all"`, where outputs are inline on the mock tree. Its
-     * presence is the signal that outputs must be fetched rather than read inline.
+     * `externalSpanId`. Present ONLY on a non-`all` path that needs a tree
+     * (`marked`, or `none` with overrides); absent under `mock: "all"`, where
+     * outputs are inline even when overrides are present. Its presence is the
+     * signal that outputs must be fetched rather than read inline.
      */
     fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
     dbBranchLease?: DbBranchLease;
@@ -1177,9 +1179,9 @@ interface DbBranchOptions {
 }
 interface ReplayOptions {
     /**
-     * Maximum number of traces to replay (1-100, default 5). Ignored when
-     * `traceIds` is passed (with a warning): an explicit ID list already
-     * determines how many traces replay.
+     * Maximum number of traces to replay (1-5,000, default 5). Ignored when
+     * `traceIds` is passed (with a warning), or when `datasetId` is passed,
+     * because either source already determines how many traces replay.
      */
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
@@ -1209,7 +1211,8 @@ interface ReplayOptions {
      * Mock strategy for child spans during replay.
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
      * - "none": everything runs real code
-     * - "all": every child withSpan returns historical output
+     * - "all": every matched recorded child withSpan returns historical output;
+     *   a missing occurrence fails the replay item closed
      */
     mock?: MockStrategy;
     /**
@@ -1229,9 +1232,10 @@ interface ReplayOptions {
      * branch with `getCurrentReplayBranch()`.
      *
      * Items whose source trace carried no DB snapshot reference get no branch and
-     * run against the live database. An item whose branch was requested but could
-     * not be resolved fails instead of running, so a replay never silently
-     * reports a result that did not use the historical data you asked for.
+     * use the app's normal database path. Unsafe calls on that path still require
+     * replay mocking. An item whose branch was requested but could not be resolved
+     * fails instead of running, so replay never silently reports a result that did
+     * not use the historical data you asked for.
      */
     dbBranch?: DbBranchOptions | boolean;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
@@ -1966,7 +1970,9 @@ interface SpanOptions {
      *
      * Use this for child spans that are expensive (paid LLM/API calls),
      * slow, or non-deterministic - the root function still runs real code,
-     * only the marked descendants return their recorded output.
+     * only the marked descendants return their recorded output. If a selected
+     * occurrence is unavailable, replay fails the item without executing the
+     * real child.
      */
     mockOnReplay?: boolean;
     /**
@@ -2575,7 +2581,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.11";
+declare const __version__ = "0.36.13";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -182,8 +182,9 @@ interface MockOverride {
  * A single span entry in the mock tree.
  *
  * Under the eager path (`mock: "all"`) `output`/`outputMeta` are populated
- * inline. Under the lazy path (`marked` / overrides) they are absent and the
- * recorded output is fetched on demand via `externalSpanId` - see
+ * inline, even when overrides are present. Under a non-`all` path that needs a
+ * tree (`marked`, or `none` with overrides), they are absent and the recorded
+ * output is fetched on demand via `externalSpanId` - see
  * {@link ReplayContext.fetchSpanOutput}.
  */
 interface MockSpan {
@@ -267,9 +268,10 @@ interface ReplayContext {
     mockOverrides?: MockOverride[];
     /**
      * Memoized lazy fetch of a span's recorded output (deserialized), keyed by
-     * `externalSpanId`. Present ONLY on the lazy path (`marked` / overrides);
-     * absent under `mock: "all"`, where outputs are inline on the mock tree. Its
-     * presence is the signal that outputs must be fetched rather than read inline.
+     * `externalSpanId`. Present ONLY on a non-`all` path that needs a tree
+     * (`marked`, or `none` with overrides); absent under `mock: "all"`, where
+     * outputs are inline even when overrides are present. Its presence is the
+     * signal that outputs must be fetched rather than read inline.
      */
     fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
     dbBranchLease?: DbBranchLease;
@@ -1177,9 +1179,9 @@ interface DbBranchOptions {
 }
 interface ReplayOptions {
     /**
-     * Maximum number of traces to replay (1-100, default 5). Ignored when
-     * `traceIds` is passed (with a warning): an explicit ID list already
-     * determines how many traces replay.
+     * Maximum number of traces to replay (1-5,000, default 5). Ignored when
+     * `traceIds` is passed (with a warning), or when `datasetId` is passed,
+     * because either source already determines how many traces replay.
      */
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
@@ -1209,7 +1211,8 @@ interface ReplayOptions {
      * Mock strategy for child spans during replay.
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
      * - "none": everything runs real code
-     * - "all": every child withSpan returns historical output
+     * - "all": every matched recorded child withSpan returns historical output;
+     *   a missing occurrence fails the replay item closed
      */
     mock?: MockStrategy;
     /**
@@ -1229,9 +1232,10 @@ interface ReplayOptions {
      * branch with `getCurrentReplayBranch()`.
      *
      * Items whose source trace carried no DB snapshot reference get no branch and
-     * run against the live database. An item whose branch was requested but could
-     * not be resolved fails instead of running, so a replay never silently
-     * reports a result that did not use the historical data you asked for.
+     * use the app's normal database path. Unsafe calls on that path still require
+     * replay mocking. An item whose branch was requested but could not be resolved
+     * fails instead of running, so replay never silently reports a result that did
+     * not use the historical data you asked for.
      */
     dbBranch?: DbBranchOptions | boolean;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
@@ -1966,7 +1970,9 @@ interface SpanOptions {
      *
      * Use this for child spans that are expensive (paid LLM/API calls),
      * slow, or non-deterministic - the root function still runs real code,
-     * only the marked descendants return their recorded output.
+     * only the marked descendants return their recorded output. If a selected
+     * occurrence is unavailable, replay fails the item without executing the
+     * real child.
      */
     mockOnReplay?: boolean;
     /**
@@ -2575,7 +2581,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.11";
+declare const __version__ = "0.36.13";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-VDFPZYLH.js";
+} from "./chunk-XAQJOZMJ.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
@@ -23,7 +23,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-EKOAKLZC.js";
+} from "./chunk-VOUV7ZTS.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.36.11";
+    __version__ = "0.36.13";
   }
 });
 
@@ -2593,20 +2593,17 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
           includeOutputs,
           includeRootOutput: false
         });
-        if (treeResponse.root) {
-          mockTree = buildMockTree(treeResponse.root);
-        } else if (mockStrategy === "all" || hasOverrides) {
+        if (!treeResponse.root) {
           throw new BitfabError(
             `Replay mock strategy "${mockStrategy}"${hasOverrides ? " with overrides" : ""} requires a span tree root for original span ${originalSpanId}.`
           );
-        } else {
-          mockTree = void 0;
         }
-      } catch (e) {
-        if (mockStrategy === "all" || hasOverrides) {
-          throw e;
+        mockTree = buildMockTree(treeResponse.root);
+      } catch (error2) {
+        if (mockStrategy !== "marked" || hasOverrides) {
+          throw error2;
         }
-        mockTree = void 0;
+        mockTree = { spans: /* @__PURE__ */ new Map() };
       }
     }
     const outputCache = /* @__PURE__ */ new Map();
@@ -6115,14 +6112,19 @@ var Bitfab = class {
           counters.set(counterKey, callIndex + 1);
           const mockKey = `${counterKey}:${callIndex}`;
           const mockSpan = replayCtxForMock.mockTree.spans.get(mockKey);
-          const emitMock = (output) => {
-            void sendSpan({ result: output, mocked: true });
+          const emitMock = (output, mockSource) => {
+            void sendSpan({
+              result: output,
+              mocked: true,
+              mockTarget: "output",
+              mockSource
+            });
             if (fnReturnsPromise) {
               return Promise.resolve(output);
             }
             return output;
           };
-          const emitMockAsync = (pending) => {
+          const emitMockAsync = (pending, mockSource) => {
             if (!fnReturnsPromise) {
               throw new BitfabError(
                 `Cannot mock synchronous span "${traceFunctionKey}" with an asynchronously-resolved value (lazy recorded-output fetch or an async value function). Make the wrapped function async, or use mock: "all" so recorded outputs are fetched eagerly.`
@@ -6130,7 +6132,12 @@ var Bitfab = class {
             }
             return (async () => {
               const output = await pending;
-              void sendSpan({ result: output, mocked: true });
+              void sendSpan({
+                result: output,
+                mocked: true,
+                mockTarget: "output",
+                mockSource
+              });
               return output;
             })();
           };
@@ -6172,18 +6179,23 @@ var Bitfab = class {
                 getOriginalOutput: () => Promise.resolve(resolveRecordedOutput())
               });
               if (injected instanceof Promise) {
-                return emitMockAsync(injected);
+                return emitMockAsync(injected, "override");
               }
-              return emitMock(injected);
+              return emitMock(injected, "override");
             }
           }
           const shouldMock = replayCtxForMock.mockStrategy === "all" || replayCtxForMock.mockStrategy === "marked" && options.mockOnReplay === true;
-          if (shouldMock && mockSpan) {
+          if (shouldMock && !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) {
             const recorded = resolveRecordedOutput();
             if (recorded instanceof Promise) {
-              return emitMockAsync(recorded);
+              return emitMockAsync(recorded, "recorded");
             }
-            return emitMock(recorded);
+            return emitMock(recorded, "recorded");
           }
         }
         const recordSpan = (result) => {
@@ -6483,7 +6495,9 @@ var Bitfab = class {
       traceFunctionKey: params.traceFunctionKey,
       rawSpan: externalSpan,
       ...params.testRunId && { testRunId: params.testRunId },
-      ...params.mocked && { mocked: true }
+      ...params.mocked && { mocked: true },
+      ...params.mockTarget && { mockTarget: params.mockTarget },
+      ...params.mockSource && { mockSource: params.mockSource }
     });
   }
   registerMockOverride(overrideOrMatch, value) {