@bitfab/sdk 0.63.0 → 0.63.2

package/dist/index.d.cts

@@ -697,7 +697,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * Blocking call - creates an experiment 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, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, skipAssertionJudging?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string, metadata?: Record<string, string>): Promise<StartReplayResponse>;
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, skipAssertionJudging?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string, metadata?: Record<string, string>, dryRun?: boolean): Promise<StartReplayResponse>;
     resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
@@ -774,8 +774,9 @@ interface CodeChangeFile {
     after: string;
 }
 interface StartReplayResponse {
-    experimentId: string;
-    experimentUrl: string;
+    /** Null for a dry run, which the server records no experiment for. */
+    experimentId: string | null;
+    experimentUrl: string | null;
     attempts?: number;
     items: Array<{
         selectiveReplayPlan?: SelectiveReplayPlan;
@@ -2251,7 +2252,9 @@ interface ReplayOptions {
      * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
      * item reports the exact arguments the function would have received. Nothing
      * executes and no replay traces are produced, which is the cheap way to check
-     * that recorded inputs still fit the current signature.
+     * that recorded inputs still fit the current signature. No experiment is
+     * created either, so the result's `experimentId` and `experimentUrl` are null
+     * and `onExperimentStart` is not called.
      */
     dryRun?: boolean;
     /**
@@ -2301,10 +2304,10 @@ interface ReplayExperiment {
 /** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
 interface ReplayItemStartProgress {
     type: "started";
-    /** Experiment ID created for this replay. */
-    experimentId: string;
+    /** Experiment ID created for this replay. Null for a dry run, which creates none. */
+    experimentId: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId: string;
+    testRunId: string | null;
     /** Items whose processing has started so far. */
     started: number;
     /** Items that have finished so far, whether they succeeded or errored. */
@@ -2330,10 +2333,10 @@ interface ReplayItemStartProgress {
 interface ReplayItemFinishProgress {
     /** Event kind, omitted for backward-compatible per-item events. */
     type?: "item";
-    /** Experiment ID created for this replay. */
-    experimentId: string;
+    /** Experiment ID created for this replay. Null for a dry run, which creates none. */
+    experimentId: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId: string;
+    testRunId: string | null;
     /** Items that have finished so far, whether they succeeded or errored. */
     completed: number;
     /** Total number of items in this replay run. */
@@ -2401,9 +2404,10 @@ interface ReplayProgressItem {
 interface ReplayProgress {
     type?: "item" | "complete";
     result?: ReplayResult<unknown>;
-    experimentId?: string;
+    /** Null for a dry run, which creates no experiment. */
+    experimentId?: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId?: string;
+    testRunId?: string | null;
     completed: number;
     total: number;
     succeeded: number;
@@ -2553,14 +2557,17 @@ interface ReplayItem<T> {
 interface ReplayResult<T> {
     /** Individual replay items with inputs, results, and comparison data. */
     items: ReplayItem<T>[];
-    /** The experiment ID created on the server. */
-    experimentId: string;
-    /** Full URL to view the experiment in the dashboard. */
-    experimentUrl: string;
+    /**
+     * The experiment ID created on the server. Null for a dry run, which
+     * executes nothing and so creates no experiment.
+     */
+    experimentId: string | null;
+    /** Full URL to view the experiment in the dashboard. Null for a dry run. */
+    experimentUrl: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId: string;
+    testRunId: string | null;
     /** @deprecated Use {@link experimentUrl}. Same value. */
-    testRunUrl: string;
+    testRunUrl: string | null;
     attempts: number;
 }
 /**
@@ -3973,7 +3980,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.63.0";
+declare const __version__ = "0.63.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -697,7 +697,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * Blocking call - creates an experiment 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, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, skipAssertionJudging?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string, metadata?: Record<string, string>): Promise<StartReplayResponse>;
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, skipAssertionJudging?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions, notes?: string, metadata?: Record<string, string>, dryRun?: boolean): Promise<StartReplayResponse>;
     resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
@@ -774,8 +774,9 @@ interface CodeChangeFile {
     after: string;
 }
 interface StartReplayResponse {
-    experimentId: string;
-    experimentUrl: string;
+    /** Null for a dry run, which the server records no experiment for. */
+    experimentId: string | null;
+    experimentUrl: string | null;
     attempts?: number;
     items: Array<{
         selectiveReplayPlan?: SelectiveReplayPlan;
@@ -2251,7 +2252,9 @@ interface ReplayOptions {
      * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
      * item reports the exact arguments the function would have received. Nothing
      * executes and no replay traces are produced, which is the cheap way to check
-     * that recorded inputs still fit the current signature.
+     * that recorded inputs still fit the current signature. No experiment is
+     * created either, so the result's `experimentId` and `experimentUrl` are null
+     * and `onExperimentStart` is not called.
      */
     dryRun?: boolean;
     /**
@@ -2301,10 +2304,10 @@ interface ReplayExperiment {
 /** Emitted through {@link ReplayOptions.onItemStart} when a worker starts an item. */
 interface ReplayItemStartProgress {
     type: "started";
-    /** Experiment ID created for this replay. */
-    experimentId: string;
+    /** Experiment ID created for this replay. Null for a dry run, which creates none. */
+    experimentId: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId: string;
+    testRunId: string | null;
     /** Items whose processing has started so far. */
     started: number;
     /** Items that have finished so far, whether they succeeded or errored. */
@@ -2330,10 +2333,10 @@ interface ReplayItemStartProgress {
 interface ReplayItemFinishProgress {
     /** Event kind, omitted for backward-compatible per-item events. */
     type?: "item";
-    /** Experiment ID created for this replay. */
-    experimentId: string;
+    /** Experiment ID created for this replay. Null for a dry run, which creates none. */
+    experimentId: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId: string;
+    testRunId: string | null;
     /** Items that have finished so far, whether they succeeded or errored. */
     completed: number;
     /** Total number of items in this replay run. */
@@ -2401,9 +2404,10 @@ interface ReplayProgressItem {
 interface ReplayProgress {
     type?: "item" | "complete";
     result?: ReplayResult<unknown>;
-    experimentId?: string;
+    /** Null for a dry run, which creates no experiment. */
+    experimentId?: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId?: string;
+    testRunId?: string | null;
     completed: number;
     total: number;
     succeeded: number;
@@ -2553,14 +2557,17 @@ interface ReplayItem<T> {
 interface ReplayResult<T> {
     /** Individual replay items with inputs, results, and comparison data. */
     items: ReplayItem<T>[];
-    /** The experiment ID created on the server. */
-    experimentId: string;
-    /** Full URL to view the experiment in the dashboard. */
-    experimentUrl: string;
+    /**
+     * The experiment ID created on the server. Null for a dry run, which
+     * executes nothing and so creates no experiment.
+     */
+    experimentId: string | null;
+    /** Full URL to view the experiment in the dashboard. Null for a dry run. */
+    experimentUrl: string | null;
     /** @deprecated Use {@link experimentId}. Same value. */
-    testRunId: string;
+    testRunId: string | null;
     /** @deprecated Use {@link experimentUrl}. Same value. */
-    testRunUrl: string;
+    testRunUrl: string | null;
     attempts: number;
 }
 /**
@@ -3973,7 +3980,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.63.0";
+declare const __version__ = "0.63.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -27,7 +27,7 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-P5NCLTE4.js";
+} from "./chunk-VLWEQEYN.js";
 import "./chunk-YWXQM6J3.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -36,7 +36,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-SXAL4FQV.js";
+} from "./chunk-IMVE24TT.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -44,7 +44,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-TSP6722V.js";
+} from "./chunk-QX7DDM5W.js";
 import "./chunk-MT36GJMW.js";
 export {
   AssertionCategoriesClient,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.63.0";
+    __version__ = "0.63.2";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2902,7 +2902,7 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * Blocking call - creates an experiment and returns lightweight item references.
        */
-      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetIds, graderIds, dbBranchSettings, attempts, includeOriginalMetadata, onlyWithAssertions, skipAssertionJudging, experimentalSelectiveReplay, notes, metadata) {
+      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetIds, graderIds, dbBranchSettings, attempts, includeOriginalMetadata, onlyWithAssertions, skipAssertionJudging, experimentalSelectiveReplay, notes, metadata, dryRun) {
         const payload = { traceFunctionKey };
         if (experimentalSelectiveReplay !== void 0) {
           payload.experimentalSelectiveReplay = experimentalSelectiveReplay;
@@ -2960,6 +2960,9 @@ var init_http = __esm({
         if (skipAssertionJudging !== true) {
           payload.judgeAssertions = true;
         }
+        if (dryRun) {
+          payload.dryRun = true;
+        }
         const git = await resolvedGitState();
         if (git && !isEmptyGitState(git)) {
           payload.git = git;
@@ -2973,7 +2976,10 @@ var init_http = __esm({
         const { testRunId, testRunUrl, ...rest } = response;
         const experimentId = response.experimentId ?? testRunId;
         const experimentUrl = response.experimentUrl ?? testRunUrl;
-        if (experimentId === void 0 || experimentUrl === void 0) {
+        if (dryRun && response.experimentId === null) {
+          return { ...rest, experimentId: null, experimentUrl: null };
+        }
+        if (experimentId === void 0 || experimentId === null || experimentUrl === void 0 || experimentUrl === null) {
           throw new BitfabError(
             "Replay start response is missing the experiment ID or URL."
           );
@@ -4309,7 +4315,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
   const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
   const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
   try {
-    if (includeDbBranchLease && !lease && !leaseError) {
+    if (includeDbBranchLease && experimentId !== null && !lease && !leaseError) {
       let resolved2;
       try {
         resolved2 = await httpClient.resolveDbBranchLease(
@@ -4403,7 +4409,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
       }
       return pending;
     } : void 0;
-    if (dryRun) {
+    if (dryRun || experimentId === null) {
       return {
         traceId: null,
         originalTraceId,
@@ -4691,7 +4697,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       options?.skipAssertionJudging === true || options?.judgeAssertions === false,
       options?.experimentalSelectiveReplay,
       options?.notes,
-      options?.metadata
+      options?.metadata,
+      options?.dryRun === true
     );
     if (started.items.length === 0) {
       try {
@@ -4721,6 +4728,22 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     );
   }
   const { experimentId } = session;
+  if (experimentId === null || session.experimentUrl === null) {
+    return runReplaySession(
+      httpClient,
+      fn,
+      session,
+      null,
+      maxConcurrency,
+      () => {
+      },
+      () => {
+      },
+      () => false,
+      options,
+      registeredOverrides
+    );
+  }
   const fullExperimentUrl = `${serviceUrl}${session.experimentUrl}`;
   const heartbeat = startReplayHeartbeat(
     () => httpClient.heartbeatReplay(experimentId)
@@ -4782,12 +4805,14 @@ function throwIfInterrupted(interrupted, items, experimentId, experimentUrl) {
 async function runReplaySession(httpClient, fn, session, fullExperimentUrl, maxConcurrency, stopInterruptingOnSignal, markCompleteReturned, interrupted, options, registeredOverrides) {
   const { experimentId, attempts } = session;
   const mockStrategy = options?.mock ?? "marked";
-  try {
-    options?.onExperimentStart?.({
-      experimentId,
-      experimentUrl: fullExperimentUrl
-    });
-  } catch {
+  if (experimentId !== null && fullExperimentUrl !== null) {
+    try {
+      options?.onExperimentStart?.({
+        experimentId,
+        experimentUrl: fullExperimentUrl
+      });
+    } catch {
+    }
   }
   const resolvedOverrides = [
     ...normalizeMockOverrides(options?.mockOverride),
@@ -4929,17 +4954,18 @@ async function runReplaySession(httpClient, fn, session, fullExperimentUrl, maxC
     interrupted
   );
   const resultItems = [...carriedOverItems, ...ranItems];
-  throwIfInterrupted(interrupted, resultItems, experimentId, fullExperimentUrl);
-  if (options?.dryRun === true) {
-    throwIfInterrupted(
-      interrupted,
-      resultItems,
-      experimentId,
-      fullExperimentUrl
-    );
-    stopInterruptingOnSignal();
-    await httpClient.completeReplay(experimentId).catch(() => void 0);
-    markCompleteReturned();
+  if (options?.dryRun === true || experimentId === null || fullExperimentUrl === null) {
+    if (experimentId !== null && fullExperimentUrl !== null) {
+      throwIfInterrupted(
+        interrupted,
+        resultItems,
+        experimentId,
+        fullExperimentUrl
+      );
+      stopInterruptingOnSignal();
+      await httpClient.completeReplay(experimentId).catch(() => void 0);
+      markCompleteReturned();
+    }
     const dryResult = {
       items: resultItems,
       experimentId,
@@ -4951,6 +4977,7 @@ async function runReplaySession(httpClient, fn, session, fullExperimentUrl, maxC
     await writeReplayResultFile(dryResult);
     return dryResult;
   }
+  throwIfInterrupted(interrupted, resultItems, experimentId, fullExperimentUrl);
   const deliveredTraceIds = await preserveReplayFailure(
     () => waitForReplayPersistence(httpClient, experimentId, replayedTraceIds),
     resultItems,