@bitfab/sdk 0.58.5 → 0.59.1

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.58.5";
+    __version__ = "0.59.1";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -2104,6 +2104,7 @@ __export(http_exports, {
   HttpClient: () => HttpClient,
   awaitOnExit: () => awaitOnExit,
   awaitPendingRequests: () => awaitPendingRequests,
+  experimentIdWireFields: () => experimentIdWireFields,
   flushTraces: () => flushTraces,
   parseRetryAfterMs: () => parseRetryAfterMs,
   serializePayloadBody: () => serializePayloadBody
@@ -2272,6 +2273,9 @@ function warnDroppedExternalTrace(error) {
     `a trace was dropped because the send step failed: ${describeError(error)}`
   );
 }
+function experimentIdWireFields(experimentId) {
+  return { experimentId, testRunId: experimentId };
+}
 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, liveHttpClients, carrierSeq, HttpClient;
 var init_http = __esm({
   "src/http.ts"() {
@@ -2876,7 +2880,7 @@ var init_http = __esm({
       }
       /**
        * Start a replay session by fetching historical traces.
-       * Blocking call - creates a test run and returns lightweight item references.
+       * 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, judgeAssertions) {
         const payload = { traceFunctionKey };
@@ -2932,9 +2936,20 @@ var init_http = __esm({
           payload.git = git;
         }
         const timeout = includeDbBranchLease ? REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS : 3e4;
-        return this.request("/api/sdk/replay/start", payload, {
-          timeout
-        });
+        const response = await this.request(
+          "/api/sdk/replay/start",
+          payload,
+          { timeout }
+        );
+        const { testRunId, testRunUrl, ...rest } = response;
+        const experimentId = response.experimentId ?? testRunId;
+        const experimentUrl = response.experimentUrl ?? testRunUrl;
+        if (experimentId === void 0 || experimentUrl === void 0) {
+          throw new BitfabError(
+            "Replay start response is missing the experiment ID or URL."
+          );
+        }
+        return { ...rest, experimentId, experimentUrl };
       }
       /**
        * Fetch an external span by ID.
@@ -3031,21 +3046,21 @@ var init_http = __esm({
        * has a final status AND at least that many persisted spans, which is what
        * makes this a real barrier rather than a "the row exists" check.
        */
-      async getReplayStatus(testRunId, expectedSpanCounts) {
+      async getReplayStatus(experimentId, expectedSpanCounts) {
         return this.request(
           "/api/sdk/replay/status",
-          { testRunId, expectedSpanCounts },
+          { ...experimentIdWireFields(experimentId), expectedSpanCounts },
           { timeout: 3e4 }
         );
       }
       /**
-       * Mark a replay test run as completed.
+       * Mark a replay experiment as completed.
        * Blocking call.
        */
-      async completeReplay(testRunId) {
+      async completeReplay(experimentId) {
         return this.request(
           "/api/sdk/replay/complete",
-          { testRunId },
+          experimentIdWireFields(experimentId),
           { timeout: REPLAY_COMPLETE_REQUEST_TIMEOUT_MS }
         );
       }
@@ -3067,11 +3082,11 @@ var init_http = __esm({
        * snapshot + preview branch and polls operations to readiness, which
        * can take seconds.
        */
-      async resolveDbBranchLease(testRunId, traceId, dbBranchSettings, attempt) {
+      async resolveDbBranchLease(experimentId, traceId, dbBranchSettings, attempt) {
         return this.request(
           "/api/sdk/replay/resolveDbBranchLease",
           {
-            testRunId,
+            ...experimentIdWireFields(experimentId),
             traceId,
             dbBranchSettings,
             ...attempt !== void 0 && attempt > 0 ? { attempt } : {}
@@ -3660,7 +3675,7 @@ function replayJsonReplacer(_key, value) {
 function serializeReplayResult(result) {
   return JSON.stringify(result, replayJsonReplacer, 2);
 }
-async function preserveReplayFailure(operation, items, testRunId, testRunUrl) {
+async function preserveReplayFailure(operation, items, experimentId, experimentUrl) {
   try {
     return await operation();
   } catch (cause) {
@@ -3670,8 +3685,8 @@ async function preserveReplayFailure(operation, items, testRunId, testRunUrl) {
     throw new ReplayError(
       errorMessage(cause),
       items,
-      testRunId,
-      testRunUrl,
+      experimentId,
+      experimentUrl,
       cause
     );
   }
@@ -3725,7 +3740,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
+async function processItem(httpClient, serverItem, fn, experimentId, 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;
@@ -3745,7 +3760,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
       let resolved2;
       try {
         resolved2 = await httpClient.resolveDbBranchLease(
-          testRunId,
+          experimentId,
           originalTraceId,
           dbBranchSettings,
           attempt
@@ -3857,7 +3872,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
       replayStarted = performance.now();
       const maybePromise = runWithReplayContext(
         {
-          testRunId,
+          experimentId,
           traceId: replayedTraceId,
           inputSourceSpanId: span.id,
           inputSourceTraceId: span.externalTraceId,
@@ -3940,14 +3955,14 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     originalTraceOutline: null
   };
 }
-async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds) {
+async function waitForReplayPersistence(httpClient, experimentId, replayedTraceIds) {
   const deferredSettled = await httpClient.settleDeferredWork(
     REPLAY_PERSISTENCE_TIMEOUT_MS
   );
   if (!deferredSettled) {
     httpClient.takeTraceDeliveries(replayedTraceIds);
     throw new BitfabError(
-      `Replay could not settle deferred span work before the deadline, so the expected span counts are incomplete (testRunId ${testRunId}).`
+      `Replay could not settle deferred span work before the deadline, so the expected span counts are incomplete (experiment ${experimentId}).`
     );
   }
   if (!httpClient.hasClosedDeliveries(replayedTraceIds)) {
@@ -3976,7 +3991,7 @@ async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds)
   let missing = Object.keys(expectedSpanCounts).length;
   while (true) {
     const status = await httpClient.getReplayStatus(
-      testRunId,
+      experimentId,
       expectedSpanCounts
     );
     const ready = status.traceIds ?? {};
@@ -3995,7 +4010,7 @@ async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds)
   }
   const cause = flushed ? "" : " Delivery was also not confirmed before the flush deadline, so the spans likely never reached the server.";
   throw new BitfabError(
-    `Replay traces were not fully persisted before the delivery deadline (testRunId ${testRunId}, missing ${missing} of ${Object.keys(expectedSpanCounts).length} trace(s)).${cause}`
+    `Replay traces were not fully persisted before the delivery deadline (experiment ${experimentId}, missing ${missing} of ${Object.keys(expectedSpanCounts).length} trace(s)).${cause}`
   );
 }
 function sleepForReplayPersistence(ms) {
@@ -4062,8 +4077,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const {
-    testRunId,
-    testRunUrl,
+    experimentId,
+    experimentUrl,
     items: serverItems
   } = await httpClient.startReplay(
     traceFunctionKey,
@@ -4096,7 +4111,14 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const mockStrategy = options?.mock ?? "marked";
-  const fullTestRunUrl = `${serviceUrl}${testRunUrl}`;
+  const fullExperimentUrl = `${serviceUrl}${experimentUrl}`;
+  try {
+    options?.onExperimentStart?.({
+      experimentId,
+      experimentUrl: fullExperimentUrl
+    });
+  } catch {
+  }
   const resolvedOverrides = [
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
@@ -4109,7 +4131,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       httpClient,
       serverItem,
       fn,
-      testRunId,
+      experimentId,
       mockStrategy,
       resolvedOverrides,
       replayedTraceIds[index],
@@ -4164,7 +4186,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
       try {
         onItemFinish?.({
-          testRunId,
+          experimentId,
+          testRunId: experimentId,
           completed,
           total,
           succeeded,
@@ -4212,7 +4235,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       try {
         options.onItemStart?.({
           type: "started",
-          testRunId,
+          experimentId,
+          testRunId: experimentId,
           started,
           completed,
           total,
@@ -4231,21 +4255,23 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     } : void 0
   );
   if (options?.dryRun === true) {
-    await httpClient.completeReplay(testRunId).catch(() => void 0);
+    await httpClient.completeReplay(experimentId).catch(() => void 0);
     const dryResult = {
       items: resultItems,
-      testRunId,
-      testRunUrl: fullTestRunUrl,
+      experimentId,
+      experimentUrl: fullExperimentUrl,
+      testRunId: experimentId,
+      testRunUrl: fullExperimentUrl,
       attempts
     };
     await writeReplayResultFile(dryResult);
     return dryResult;
   }
   const deliveredTraceIds = await preserveReplayFailure(
-    () => waitForReplayPersistence(httpClient, testRunId, replayedTraceIds),
+    () => waitForReplayPersistence(httpClient, experimentId, replayedTraceIds),
     resultItems,
-    testRunId,
-    fullTestRunUrl
+    experimentId,
+    fullExperimentUrl
   );
   for (let index = 0; index < resultItems.length; index += 1) {
     const localId = replayedTraceIds[index];
@@ -4255,10 +4281,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const completeResult = await preserveReplayFailure(
-    () => httpClient.completeReplay(testRunId),
+    () => httpClient.completeReplay(experimentId),
     resultItems,
-    testRunId,
-    fullTestRunUrl
+    experimentId,
+    fullExperimentUrl
   );
   const serverTraceIds = completeResult.traceIds;
   const replayTokens = completeResult.tokens;
@@ -4285,20 +4311,20 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     if (completedCount > 0 && missing.length === completedCount) {
       const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
       const cause = new BitfabError(
-        `Replay completed but the server has no persisted trace for any of the ${completedCount} completed item(s) (testRunId ${testRunId}).${serverCount} Trace uploads were awaited, so either the uploads failed (check for "Bitfab: Failed to create" errors above) or the replayed function is not wrapped with withSpan.`
+        `Replay completed but the server has no persisted trace for any of the ${completedCount} completed item(s) (experiment ${experimentId}).${serverCount} Trace uploads were awaited, so either the uploads failed (check for "Bitfab: Failed to create" errors above) or the replayed function is not wrapped with withSpan.`
       );
       throw new ReplayError(
         cause.message,
         resultItems,
-        testRunId,
-        fullTestRunUrl,
+        experimentId,
+        fullExperimentUrl,
         cause
       );
     }
     if (missing.length > 0) {
       try {
         console.error(
-          `Bitfab: server has no persisted trace for ${missing.length} of ${completedCount} completed replay item(s) (testRunId ${testRunId}). Their replay token usage is unavailable and they cannot be labeled.`
+          `Bitfab: server has no persisted trace for ${missing.length} of ${completedCount} completed replay item(s) (experiment ${experimentId}). Their replay token usage is unavailable and they cannot be labeled.`
         );
       } catch {
       }
@@ -4306,8 +4332,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   }
   const result = {
     items: resultItems,
-    testRunId,
-    testRunUrl: fullTestRunUrl,
+    experimentId,
+    experimentUrl: fullExperimentUrl,
+    testRunId: experimentId,
+    testRunUrl: fullExperimentUrl,
     attempts
   };
   await writeReplayResultFile(result);
@@ -4315,7 +4343,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     try {
       options?.onProgress?.({
         type: "complete",
-        testRunId,
+        experimentId,
+        testRunId: experimentId,
         completed: total,
         total,
         succeeded,
@@ -4365,13 +4394,15 @@ var init_replay = __esm({
     MAX_REPLAY_ATTEMPTS = 100;
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
     ReplayError = class extends BitfabError {
-      constructor(message, items, testRunId, testRunUrl, cause) {
-        super(message, testRunUrl);
+      constructor(message, items, experimentId, experimentUrl, cause) {
+        super(message, experimentUrl);
         this.items = items;
-        this.testRunId = testRunId;
-        this.testRunUrl = testRunUrl;
+        this.experimentId = experimentId;
+        this.experimentUrl = experimentUrl;
         this.cause = cause;
         this.name = "ReplayError";
+        this.testRunId = experimentId;
+        this.testRunUrl = experimentUrl;
       }
     };
     DbBranchReplayError = class extends BitfabError {
@@ -4390,6 +4421,8 @@ var init_replay = __esm({
 var index_exports = {};
 __export(index_exports, {
   AssertionCategoriesClient: () => AssertionCategoriesClient,
+  AssertionGenerationError: () => AssertionGenerationError,
+  AssertionGenerationTimeoutError: () => AssertionGenerationTimeoutError,
   BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
   Bitfab: () => Bitfab,
   BitfabClaudeAgentHandler: () => BitfabClaudeAgentHandler,
@@ -4405,6 +4438,8 @@ __export(index_exports, {
   DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
   DatasetsClient: () => DatasetsClient,
   DbBranchReplayError: () => DbBranchReplayError,
+  GraderRerunError: () => GraderRerunError,
+  GraderRerunTimeoutError: () => GraderRerunTimeoutError,
   GradersClient: () => GradersClient,
   HttpClient: () => HttpClient,
   LabelsClient: () => LabelsClient,
@@ -5832,11 +5867,39 @@ init_constants();
 
 // src/datasets.ts
 var DEFAULT_RERUN_TIMEOUT_MS = 9e4;
-var DEFAULT_RERUN_POLL_INTERVAL_MS = 1e3;
+var RERUN_POLL_INTERVAL_MS = 1e3;
 var TERMINAL_RERUN_STATUSES = /* @__PURE__ */ new Set([
   "completed",
   "errored"
 ]);
+var GraderRerunError = class extends Error {
+  constructor(message, run) {
+    super(message);
+    this.run = run;
+    this.name = "GraderRerunError";
+  }
+};
+var GraderRerunTimeoutError = class extends GraderRerunError {
+  constructor(datasetId, run, timeoutMs) {
+    super(
+      `Grader re-run ${run.id} on dataset ${datasetId} was still ${run.status} after ${timeoutMs}ms. It keeps running on Bitfab; read it later with getGraderRerun.`,
+      run
+    );
+    this.name = "GraderRerunTimeoutError";
+  }
+};
+function finishedRerun(datasetId, run, joinedExisting) {
+  if (!TERMINAL_RERUN_STATUSES.has(run.status)) {
+    return null;
+  }
+  if (run.status === "errored") {
+    throw new GraderRerunError(
+      `Grader re-run ${run.id} on dataset ${datasetId} errored: ${run.error ?? "no reason recorded"}`,
+      run
+    );
+  }
+  return { run, joinedExisting };
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -5936,28 +5999,25 @@ var DatasetsClient = class {
       { graderIds }
     );
   }
-  /**
-   * Re-run graders over every trace in the dataset. Defaults to every assigned
-   * grader; an unassigned id is rejected. Waits for the run to finish (up to
-   * `timeoutMs`, default 90s) unless `wait` is `false`, and returns the last
-   * run state seen either way. A request matching an in-flight run joins it.
-   */
   async rerunGraders(datasetId, options = {}) {
     const started = await this.httpClient.request(
       datasetPath(datasetId, "/rerunGraders"),
       options.graderIds === void 0 ? {} : { graderIds: options.graderIds }
     );
-    if (options.wait === false) {
-      return started;
-    }
-    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_RERUN_TIMEOUT_MS);
-    const interval = options.pollIntervalMs ?? DEFAULT_RERUN_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_RERUN_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
     let run = started.run;
-    while (!TERMINAL_RERUN_STATUSES.has(run.status) && Date.now() < deadline) {
-      await sleep(interval);
+    while (true) {
+      const finished = finishedRerun(datasetId, run, started.joinedExisting);
+      if (finished !== null) {
+        return finished;
+      }
+      if (Date.now() >= deadline) {
+        throw new GraderRerunTimeoutError(datasetId, run, timeoutMs);
+      }
+      await sleep(RERUN_POLL_INTERVAL_MS);
       run = await this.getGraderRerun(datasetId, run.id) ?? run;
     }
-    return { run, joinedExisting: started.joinedExisting };
   }
   /**
    * The dataset's active grader re-run, or the run named by `runId`. Returns
@@ -6028,6 +6088,7 @@ var GradersClient = class {
 init_http();
 
 // src/labels.ts
+init_http();
 var LABELS_PATH = "/api/sdk/traces/labels";
 var HUMAN_LABELS_PATH = "/api/sdk/traces/labels/human";
 function labelEvidencePath(traceId, assertionId) {
@@ -6037,27 +6098,27 @@ var LabelsClient = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
-  async save(update, testRunId) {
-    const [outcome] = await this.saveAll([update], testRunId);
+  async save(update, experimentId) {
+    const [outcome] = await this.saveAll([update], experimentId);
     return outcome;
   }
-  async saveAll(updates, testRunId) {
+  async saveAll(updates, experimentId) {
     const response = await this.httpClient.request(
       LABELS_PATH,
       {
         labels: updates,
-        ...testRunId === void 0 ? {} : { testRunId }
+        ...experimentId === void 0 ? {} : experimentIdWireFields(experimentId)
       }
     );
     return response.labels;
   }
   /** Withhold a verdict for a trace or replay attempt whose check did not run. */
-  async skip(target, testRunId) {
-    return this.save({ ...target, skip: true }, testRunId);
+  async skip(target, experimentId) {
+    return this.save({ ...target, skip: true }, experimentId);
   }
   /** Clear a previous verdict for a trace, replay attempt, or assertion. */
-  async archive(target, testRunId) {
-    return this.save({ ...target, archive: true }, testRunId);
+  async archive(target, experimentId) {
+    return this.save({ ...target, archive: true }, experimentId);
   }
   async saveHuman(update) {
     const [outcome] = await this.saveHumanAll([update]);
@@ -7813,6 +7874,46 @@ init_traceMetadata();
 // src/traces.ts
 var ASSERTIONS_PATH = "/api/sdk/traces/assertions";
 var SEARCH_PATH = "/api/sdk/traces/search";
+var DEFAULT_GENERATION_TIMEOUT_MS = 6e5;
+var GENERATION_POLL_INTERVAL_MS = 2e3;
+var AssertionGenerationError = class extends Error {
+  constructor(message, traceId) {
+    super(message);
+    this.traceId = traceId;
+    this.name = "AssertionGenerationError";
+  }
+};
+var AssertionGenerationTimeoutError = class extends AssertionGenerationError {
+  constructor(traceId, timeoutMs) {
+    super(
+      `Assertion generation for trace ${traceId} did not finish within ${timeoutMs}ms. Generation keeps running on Bitfab. Call getAssertions and read its generation field to check its status.`,
+      traceId
+    );
+    this.name = "AssertionGenerationTimeoutError";
+  }
+};
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isGenerationFinished(traceId, generation) {
+  if (generation === null || generation.status === "running") {
+    return false;
+  }
+  if (generation.status === "failed") {
+    throw new AssertionGenerationError(
+      `Assertion generation for trace ${traceId} failed: ${generation.error ?? "no reason recorded"}. Pass regenerate: true to try again.`,
+      traceId
+    );
+  }
+  return true;
+}
+function draftsInGenerationOrder(assertions, assertionIds) {
+  const byId = new Map(assertions.map((assertion) => [assertion.id, assertion]));
+  return assertionIds.flatMap((id) => {
+    const assertion = byId.get(id);
+    return assertion === void 0 ? [] : [assertion];
+  });
+}
 function traceAssertionsPath(traceId, suffix = "") {
   return `/api/sdk/traces/${encodeURIComponent(traceId)}/assertions${suffix}`;
 }
@@ -7844,6 +7945,34 @@ var TracesClient = class {
     });
     return response.assertions;
   }
+  async generateAssertions(traceId, options = {}) {
+    const started = await this.httpClient.request(
+      traceAssertionsPath(traceId, "/generate"),
+      {
+        ...options.guidance === void 0 ? {} : { guidance: options.guidance },
+        ...options.categoryIds === void 0 ? {} : { categoryIds: options.categoryIds },
+        ...options.regenerate === void 0 ? {} : { regenerate: options.regenerate }
+      }
+    );
+    if (isGenerationFinished(traceId, started.generation)) {
+      return started.assertions;
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_GENERATION_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      if (Date.now() >= deadline) {
+        throw new AssertionGenerationTimeoutError(traceId, timeoutMs);
+      }
+      await sleep2(GENERATION_POLL_INTERVAL_MS);
+      const read2 = await this.getAssertions(traceId);
+      if (isGenerationFinished(traceId, read2.generation)) {
+        return draftsInGenerationOrder(
+          read2.assertions,
+          read2.generation.assertionIds
+        );
+      }
+    }
+  }
   async archiveAssertions(params) {
     const response = await this.httpClient.request(
       traceAssertionsPath(params.traceId, "/archive"),
@@ -8347,6 +8476,15 @@ var BitfabVercelAiHandler = class {
 
 // src/client.ts
 init_warnOnce();
+function resolveSpanExperimentId(options) {
+  const { experimentId, testRunId } = options;
+  if (experimentId !== void 0 && testRunId !== void 0 && experimentId !== testRunId) {
+    throw new BitfabError(
+      `experimentId ("${experimentId}") and its deprecated alias testRunId ("${testRunId}") were both passed with different values. Pass only experimentId.`
+    );
+  }
+  return experimentId ?? testRunId;
+}
 var TRUNCATION_LIMIT_ORDER = [
   "max_depth",
   "max_captured_subtree_spans"
@@ -8936,13 +9074,12 @@ var Bitfab = class {
         "bitfab.node({ capture: false }) cannot use mockOnReplay: true because an uncaptured node has no recorded output."
       );
     }
+    const experimentId = resolveSpanExperimentId(options);
     return {
       capture,
       type: options.type ?? "custom",
       ...options.name !== void 0 && { name: options.name },
-      ...options.testRunId !== void 0 && {
-        testRunId: options.testRunId
-      },
+      ...experimentId !== void 0 && { experimentId },
       ...options.mockOnReplay !== void 0 && {
         mockOnReplay: options.mockOnReplay
       },
@@ -9077,6 +9214,7 @@ var Bitfab = class {
               return invokeWithoutNode();
             }
             const mockOnReplay = nodeConfiguration?.mockOnReplay ?? options.mockOnReplayDefault;
+            const nodeExperimentId = nodeConfiguration === void 0 ? void 0 : resolveSpanExperimentId(nodeConfiguration);
             const childOptions = {
               name: spanName,
               type: nodeConfiguration?.type ?? "function",
@@ -9087,8 +9225,8 @@ var Bitfab = class {
               captureContent: true,
               autoTraceDefinition: definition,
               ...declaredNode && { declaredNode },
-              ...nodeConfiguration?.testRunId !== void 0 && {
-                testRunId: nodeConfiguration.testRunId
+              ...nodeExperimentId !== void 0 && {
+                experimentId: nodeExperimentId
               },
               ...mockOnReplay !== void 0 && {
                 mockOnReplay
@@ -9749,6 +9887,7 @@ var Bitfab = class {
     const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
     const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
     const self = this;
+    const optionExperimentId = resolveSpanExperimentId(options);
     const fnIsAsyncFunction = fn.constructor.name === "AsyncFunction";
     const fnReturnsPromise = fnIsAsyncFunction || (() => {
       try {
@@ -9851,7 +9990,7 @@ var Bitfab = class {
         const inputs = args;
         const startedAt = nowIsoTimestamp();
         const replayCtxAtStart = getReplayContext();
-        const testRunId = replayCtxAtStart?.testRunId ?? options.testRunId;
+        const experimentId = replayCtxAtStart?.experimentId ?? optionExperimentId;
         if (isRootSpan && !activeTraceStates.has(traceId)) {
           const dbSnapshotRef = buildSnapshotRef(self.dbSnapshot, startedAt);
           self.simulationPlan.refresh();
@@ -9860,7 +9999,7 @@ var Bitfab = class {
             traceFunctionKey,
             startedAt,
             contexts: [],
-            ...testRunId !== void 0 && { testRunId },
+            ...experimentId !== void 0 && { experimentId },
             ...replayCtxAtStart?.inputSourceTraceId && {
               inputSourceTraceId: replayCtxAtStart.inputSourceTraceId
             },
@@ -9906,7 +10045,7 @@ var Bitfab = class {
                 contexts: newContext.contexts,
                 prompt: newContext.prompt,
                 endedAt,
-                ...testRunId !== void 0 && { testRunId },
+                ...experimentId !== void 0 && { experimentId },
                 ...replayCtx?.inputSourceSpanId && {
                   inputSourceSpanId: replayCtx.inputSourceSpanId
                 }
@@ -9927,7 +10066,7 @@ var Bitfab = class {
                 name: traceState?.name,
                 metadata: callerTraceMetadata(traceId),
                 contexts: traceState?.contexts ?? [],
-                testRunId: traceState?.testRunId,
+                experimentId: traceState?.experimentId,
                 inputSourceTraceId: traceState?.inputSourceTraceId,
                 replayAttempt: traceState?.replayAttempt,
                 dbSnapshotRef: traceState?.dbSnapshotRef,
@@ -10398,7 +10537,7 @@ var Bitfab = class {
       completed: true,
       ...params.dropped && { dropped: true },
       ...params.sessionId && { sessionId: params.sessionId },
-      ...params.testRunId && { testRunId: params.testRunId }
+      ...params.experimentId !== void 0 && experimentIdWireFields(params.experimentId)
     });
   }
   sendsSpanOnCompletion(context) {
@@ -10510,7 +10649,7 @@ var Bitfab = class {
       },
       ...params.declaredNode === true && { [DECLARED_NODE_FIELD]: true },
       rawSpan: externalSpan,
-      ...params.testRunId && { testRunId: params.testRunId },
+      ...params.experimentId !== void 0 && experimentIdWireFields(params.experimentId),
       ...params.mocked && { mocked: true },
       ...params.mockTarget && { mockTarget: params.mockTarget },
       ...params.mockSource && { mockSource: params.mockSource }
@@ -11062,6 +11201,8 @@ function resolveTraceFunctionKey(registration) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AssertionCategoriesClient,
+  AssertionGenerationError,
+  AssertionGenerationTimeoutError,
   BITFAB_PROGRESS_PREFIX,
   Bitfab,
   BitfabClaudeAgentHandler,
@@ -11077,6 +11218,8 @@ function resolveTraceFunctionKey(registration) {
   DEFAULT_SERVICE_URL,
   DatasetsClient,
   DbBranchReplayError,
+  GraderRerunError,
+  GraderRerunTimeoutError,
   GradersClient,
   HttpClient,
   LabelsClient,