@bitfab/sdk 0.41.0 → 0.42.0

package/dist/index.d.cts

@@ -306,6 +306,7 @@ interface ReplayContext {
      * customer sees in the Bitfab dashboard.
      */
     sourceBitfabTraceId?: string;
+    replayAttempt?: number;
     mockTree?: MockTree;
     callCounters?: Map<string, number>;
     mockStrategy?: "none" | "all" | "marked";
@@ -584,7 +585,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * Blocking call - creates a test run and returns lightweight item references.
      */
-    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetId?: string, graderIds?: string[], dbBranchSettings?: DbBranchSettings): Promise<StartReplayResponse>;
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetId?: string, graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number): Promise<StartReplayResponse>;
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
@@ -625,7 +626,7 @@ declare class HttpClient {
      * snapshot + preview branch and polls operations to readiness, which
      * can take seconds.
      */
-    resolveDbBranchLease(testRunId: string, traceId: string, dbBranchSettings?: DbBranchSettings): Promise<{
+    resolveDbBranchLease(testRunId: string, traceId: string, dbBranchSettings?: DbBranchSettings, attempt?: number): Promise<{
         dbSnapshotRef: DbSnapshotRef | null;
         lease: DbBranchLease | null;
         leaseError: {
@@ -658,6 +659,7 @@ interface CodeChangeFile {
 interface StartReplayResponse {
     testRunId: string;
     testRunUrl: string;
+    attempts?: number;
     items: Array<{
         /** Bitfab trace ID of the original (historical) trace being replayed. */
         originalTraceId?: string;
@@ -1472,6 +1474,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
+    attempts?: number;
     /** 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. */
@@ -1624,6 +1627,7 @@ interface ReplayItemStartProgress {
         sourceTraceId: string;
         /** @deprecated alias for `originalSpanId`. */
         sourceSpanId: string;
+        attempt: number;
     };
 }
 /** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
@@ -1663,6 +1667,7 @@ interface ReplayProgressItem {
     sourceTraceId: string | null;
     /** @deprecated alias for `originalSpanId`. */
     sourceSpanId?: string | null;
+    attempt: number;
     /** Deserialized inputs from the original trace. */
     input?: unknown[];
     /** The result returned by the replayed function, or undefined on error. */
@@ -1772,6 +1777,7 @@ interface ReplayItem<T> {
     sourceTraceId: string;
     /** @deprecated alias for {@link ReplayItem.originalSpanId}. */
     sourceSpanId: string;
+    attempt: number;
     /** Deserialized inputs from the original trace. */
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
@@ -1850,6 +1856,7 @@ interface ReplayResult<T> {
     testRunId: string;
     /** Full URL to view the test run in the dashboard. */
     testRunUrl: string;
+    attempts: number;
 }
 /**
  * Whole-run replay failure that preserves every item collected before the run
@@ -3100,7 +3107,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.41.0";
+declare const __version__ = "0.42.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -306,6 +306,7 @@ interface ReplayContext {
      * customer sees in the Bitfab dashboard.
      */
     sourceBitfabTraceId?: string;
+    replayAttempt?: number;
     mockTree?: MockTree;
     callCounters?: Map<string, number>;
     mockStrategy?: "none" | "all" | "marked";
@@ -584,7 +585,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * Blocking call - creates a test run and returns lightweight item references.
      */
-    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetId?: string, graderIds?: string[], dbBranchSettings?: DbBranchSettings): Promise<StartReplayResponse>;
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetId?: string, graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number): Promise<StartReplayResponse>;
     /**
      * Fetch an external span by ID.
      * Blocking GET request.
@@ -625,7 +626,7 @@ declare class HttpClient {
      * snapshot + preview branch and polls operations to readiness, which
      * can take seconds.
      */
-    resolveDbBranchLease(testRunId: string, traceId: string, dbBranchSettings?: DbBranchSettings): Promise<{
+    resolveDbBranchLease(testRunId: string, traceId: string, dbBranchSettings?: DbBranchSettings, attempt?: number): Promise<{
         dbSnapshotRef: DbSnapshotRef | null;
         lease: DbBranchLease | null;
         leaseError: {
@@ -658,6 +659,7 @@ interface CodeChangeFile {
 interface StartReplayResponse {
     testRunId: string;
     testRunUrl: string;
+    attempts?: number;
     items: Array<{
         /** Bitfab trace ID of the original (historical) trace being replayed. */
         originalTraceId?: string;
@@ -1472,6 +1474,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
+    attempts?: number;
     /** 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. */
@@ -1624,6 +1627,7 @@ interface ReplayItemStartProgress {
         sourceTraceId: string;
         /** @deprecated alias for `originalSpanId`. */
         sourceSpanId: string;
+        attempt: number;
     };
 }
 /** Running totals reported to {@link ReplayOptions.onItemFinish} as replay proceeds. */
@@ -1663,6 +1667,7 @@ interface ReplayProgressItem {
     sourceTraceId: string | null;
     /** @deprecated alias for `originalSpanId`. */
     sourceSpanId?: string | null;
+    attempt: number;
     /** Deserialized inputs from the original trace. */
     input?: unknown[];
     /** The result returned by the replayed function, or undefined on error. */
@@ -1772,6 +1777,7 @@ interface ReplayItem<T> {
     sourceTraceId: string;
     /** @deprecated alias for {@link ReplayItem.originalSpanId}. */
     sourceSpanId: string;
+    attempt: number;
     /** Deserialized inputs from the original trace. */
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
@@ -1850,6 +1856,7 @@ interface ReplayResult<T> {
     testRunId: string;
     /** Full URL to view the test run in the dashboard. */
     testRunUrl: string;
+    attempts: number;
 }
 /**
  * Whole-run replay failure that preserves every item collected before the run
@@ -3100,7 +3107,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.41.0";
+declare const __version__ = "0.42.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   getCurrentSpan,
   getCurrentTrace,
   seedFromRegistry
-} from "./chunk-U3AKIFW3.js";
+} from "./chunk-BC5OYWAM.js";
 import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -24,14 +24,14 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-RWZYZRYI.js";
+} from "./chunk-BG3A5HNC.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   HttpClient,
   __version__,
   flushTraces
-} from "./chunk-IFYX3KW6.js";
+} from "./chunk-UGFTBSGS.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.41.0";
+    __version__ = "0.42.0";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -1344,7 +1344,7 @@ function sourceTraceIdOf(payload) {
   const id = rawTrace?.id;
   return typeof id === "string" ? id : void 0;
 }
-var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, carrierSeq, HttpClient;
+var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, REPLAY_COMPLETE_REQUEST_TIMEOUT_MS, OTLP_TRACES_ENDPOINT, RETRYABLE_STATUSES, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, carrierSeq, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
     "use strict";
@@ -1358,6 +1358,7 @@ var init_http = __esm({
     init_unrefTimer();
     init_warnOnce();
     REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS = 3e5;
+    REPLAY_COMPLETE_REQUEST_TIMEOUT_MS = 12e4;
     OTLP_TRACES_ENDPOINT = "/api/sdk/otel/v1/traces";
     RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
     EXIT_FLUSH_TIMEOUT_MS = 5e3;
@@ -1847,7 +1848,7 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * Blocking call - creates a test run and returns lightweight item references.
        */
-      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings) {
+      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings, attempts) {
         const payload = { traceFunctionKey };
         if (limit !== void 0) {
           payload.limit = limit;
@@ -1880,6 +1881,9 @@ var init_http = __esm({
         if (dbBranchSettings !== void 0) {
           payload.dbBranchSettings = dbBranchSettings;
         }
+        if (attempts !== void 0 && attempts > 1) {
+          payload.attempts = attempts;
+        }
         const timeout = includeDbBranchLease ? REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS : 3e4;
         return this.request("/api/sdk/replay/start", payload, {
           timeout
@@ -1995,7 +1999,7 @@ var init_http = __esm({
         return this.request(
           "/api/sdk/replay/complete",
           { testRunId },
-          { timeout: 3e4 }
+          { timeout: REPLAY_COMPLETE_REQUEST_TIMEOUT_MS }
         );
       }
       /**
@@ -2004,10 +2008,15 @@ var init_http = __esm({
        * snapshot + preview branch and polls operations to readiness, which
        * can take seconds.
        */
-      async resolveDbBranchLease(testRunId, traceId, dbBranchSettings) {
+      async resolveDbBranchLease(testRunId, traceId, dbBranchSettings, attempt) {
         return this.request(
           "/api/sdk/replay/resolveDbBranchLease",
-          { testRunId, traceId, dbBranchSettings },
+          {
+            testRunId,
+            traceId,
+            dbBranchSettings,
+            ...attempt !== void 0 && attempt > 0 ? { attempt } : {}
+          },
           { timeout: REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS }
         );
       }
@@ -2443,6 +2452,23 @@ __export(replay_exports, {
   sleepForReplayPersistence: () => sleepForReplayPersistence,
   waitForReplayPersistence: () => waitForReplayPersistence
 });
+function expandReplayWork(serverItems, attempts) {
+  return Array.from(
+    { length: attempts },
+    (_, attempt) => serverItems.map((serverItem) => ({ serverItem, attempt }))
+  ).flat();
+}
+function resolveAttempts(attempts) {
+  if (attempts === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(attempts) || attempts < 1 || attempts > MAX_REPLAY_ATTEMPTS) {
+    throw new BitfabError(
+      `attempts must be an integer from 1 to ${MAX_REPLAY_ATTEMPTS} (got ${attempts}).`
+    );
+  }
+  return attempts;
+}
 function dbBranchEnabled(dbBranch) {
   return dbBranch !== void 0 && dbBranch !== false;
 }
@@ -2566,7 +2592,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
   let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
   let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
   let dbSnapshotRef = serverItem.dbSnapshotRef;
@@ -2588,7 +2614,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         resolved = await httpClient.resolveDbBranchLease(
           testRunId,
           originalTraceId,
-          dbBranchSettings
+          dbBranchSettings,
+          attempt
         );
       } catch (cause) {
         throw new DbBranchReplayError(
@@ -2668,6 +2695,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         originalSpanId,
         sourceTraceId: originalTraceId,
         sourceSpanId: originalSpanId,
+        attempt,
         input: inputs,
         result: void 0,
         originalOutput,
@@ -2696,6 +2724,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
           inputSourceSpanId: span.id,
           inputSourceTraceId: span.externalTraceId,
           sourceBitfabTraceId: originalTraceId,
+          replayAttempt: attempt,
           mockTree,
           callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
           mockStrategy,
@@ -2747,6 +2776,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     // Deprecated aliases for originalTraceId/originalSpanId.
     sourceTraceId: originalTraceId,
     sourceSpanId: originalSpanId,
+    attempt,
     input: inputs,
     result,
     originalOutput,
@@ -2875,6 +2905,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     } catch {
     }
   }
+  const attempts = resolveAttempts(options?.attempts);
   await replayContextReady;
   let codeChangeDescription = options?.codeChangeDescription;
   let codeChangeFiles = options?.codeChangeFiles;
@@ -2907,7 +2938,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     options?.experimentGroupId,
     options?.datasetId,
     options?.graderIds,
-    resolveDbBranchSettings(options?.dbBranch)
+    resolveDbBranchSettings(options?.dbBranch),
+    attempts
   );
   if (serverItems.length === 0) {
     try {
@@ -2924,10 +2956,11 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
   ];
-  const replayedTraceIds = serverItems.map(() => randomUuid());
+  const workItems = expandReplayWork(serverItems, attempts);
+  const replayedTraceIds = workItems.map(() => randomUuid());
   httpClient.trackTraceDeliveries(replayedTraceIds);
-  const tasks = serverItems.map(
-    (serverItem, index) => () => processItem(
+  const tasks = workItems.map(
+    ({ serverItem, attempt }, index) => () => processItem(
       httpClient,
       serverItem,
       fn,
@@ -2935,6 +2968,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       mockStrategy,
       resolvedOverrides,
       replayedTraceIds[index],
+      attempt,
       dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
       resolveDbBranchSettings(options?.dbBranch),
       options?.adaptInputs,
@@ -3002,6 +3036,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             // Deprecated aliases for originalTraceId/originalSpanId.
             sourceTraceId: item.originalTraceId ?? null,
             sourceSpanId: item.originalSpanId ?? null,
+            attempt: item.attempt,
             input: item.input,
             result: item.result,
             originalOutput: item.originalOutput,
@@ -3023,7 +3058,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     },
     options?.onItemStart ? (index) => {
       started += 1;
-      const serverItem = serverItems[index];
+      const { serverItem, attempt } = workItems[index];
       const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
       const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
       try {
@@ -3039,7 +3074,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             originalTraceId,
             originalSpanId,
             sourceTraceId: originalTraceId,
-            sourceSpanId: originalSpanId
+            sourceSpanId: originalSpanId,
+            attempt
           }
         });
       } catch {
@@ -3051,7 +3087,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     const dryResult = {
       items: resultItems,
       testRunId,
-      testRunUrl: fullTestRunUrl
+      testRunUrl: fullTestRunUrl,
+      attempts
     };
     await writeReplayResultFile(dryResult);
     return dryResult;
@@ -3120,7 +3157,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   const result = {
     items: resultItems,
     testRunId,
-    testRunUrl: fullTestRunUrl
+    testRunUrl: fullTestRunUrl,
+    attempts
   };
   await writeReplayResultFile(result);
   if (!options?.onItemFinish) {
@@ -3161,7 +3199,7 @@ async function writeReplayResultFile(result) {
     }
   }
 }
-var REPLAY_PERSISTENCE_TIMEOUT_MS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
+var REPLAY_PERSISTENCE_TIMEOUT_MS, MAX_REPLAY_ATTEMPTS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -3173,6 +3211,7 @@ var init_replay = __esm({
     init_replayContext();
     init_serialize();
     REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
+    MAX_REPLAY_ATTEMPTS = 100;
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
     ReplayError = class extends BitfabError {
       constructor(message, items, testRunId, testRunUrl, cause) {
@@ -7026,6 +7065,9 @@ var Bitfab = class {
             ...replayCtxAtStart?.inputSourceTraceId && {
               inputSourceTraceId: replayCtxAtStart.inputSourceTraceId
             },
+            ...replayCtxAtStart?.replayAttempt !== void 0 && {
+              replayAttempt: replayCtxAtStart.replayAttempt
+            },
             dbSnapshotRef
           });
           registeredTraceId = traceId;
@@ -7076,6 +7118,7 @@ var Bitfab = class {
                 contexts: traceState?.contexts ?? [],
                 testRunId: traceState?.testRunId,
                 inputSourceTraceId: traceState?.inputSourceTraceId,
+                replayAttempt: traceState?.replayAttempt,
                 dbSnapshotRef: traceState?.dbSnapshotRef,
                 dropped: traceState?.dropped,
                 ingestionType: traceState?.ingestionType,
@@ -7473,6 +7516,9 @@ var Bitfab = class {
     if (params.inputSourceTraceId) {
       rawTrace.input_source_trace_id = params.inputSourceTraceId;
     }
+    if (params.replayAttempt !== void 0) {
+      rawTrace.replay_attempt = params.replayAttempt;
+    }
     if (params.dbSnapshotRef) {
       rawTrace.db_snapshot_ref = params.dbSnapshotRef;
     }