@bitfab/sdk 0.29.0 → 0.30.0

package/dist/index.d.cts

@@ -749,6 +749,15 @@ interface ReplayOptions {
      * reconstructed. Validated server-side against the org.
      */
     datasetId?: string;
+    /**
+     * Graders to attach directly to this experiment (test run), independent of any
+     * graders already on the dataset. The resulting experiment is graded by the
+     * union of these and the dataset's runnable graders at completion, so use this
+     * to grade a single run with a check you don't want to add to the dataset
+     * permanently. Each id must be an active/live grader belonging to the same
+     * organization and trace function, otherwise the server rejects the replay.
+     */
+    graderIds?: string[];
     /**
      * Reshape recorded inputs before they are spread into `fn`.
      *
@@ -785,6 +794,21 @@ interface ReplayOptions {
 }
 /** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
 interface ReplayProgress {
+    /**
+     * Event kind. Omitted (or `"item"`) for the per-trace settle events streamed
+     * during the run. `"complete"` marks the single terminal event emitted once
+     * the run has settled and been enriched server-side; it carries the full
+     * {@link ReplayProgress.result} and has no `item`. The Bitfab plugin reads
+     * that terminal event to build the run's final result without parsing stdout.
+     */
+    type?: "item" | "complete";
+    /**
+     * The full {@link ReplayResult}, present only on the terminal `"complete"`
+     * event. Lets the plugin ingest the enriched result (server-aggregated tokens,
+     * server trace ids) over the same channel as progress, so a dependency logging
+     * to stdout can never block it.
+     */
+    result?: ReplayResult<unknown>;
     /** Test run ID created for this replay. */
     testRunId?: string;
     /** Items that have finished so far, whether they succeeded or errored. */
@@ -796,18 +820,25 @@ interface ReplayProgress {
     /** Of the completed items, how many threw (their `item.error` is set). */
     errored: number;
     /**
-     * The single item that just settled to produce this event. `traceId` is the
-     * source (historical) trace that was replayed (so a UI can identify or link
-     * it); `error` is its replay error, or null when it ran ok; `durationMs` is how
-     * long this one trace took to replay. Lets a progress UI show per-trace
-     * pass/fail and timing as the run streams, without waiting for the full
-     * {@link ReplayResult}.
+     * The single item that just settled to produce this event. `traceId` is null
+     * at this stage (the server replay id isn't known until the run completes);
+     * `originalTraceId` is the original (historical) trace that was replayed (so
+     * a UI can identify or link it); `error` is its replay error, or null when it
+     * ran ok; `durationMs` is how long this one trace took to replay. Lets a
+     * progress UI show per-trace pass/fail and timing as the run streams, without
+     * waiting for the full {@link ReplayResult}.
      */
     item?: {
-        /** Source (historical) trace ID being replayed. */
-        traceId: string | null;
-        /** Local SDK replay trace ID, before the server maps it to a row ID. */
-        replayTraceId?: string | null;
+        /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
+        traceId?: string | null;
+        /** Bitfab trace ID of the original (historical) trace being replayed. */
+        originalTraceId: string | null;
+        /** External span ID the recorded inputs were read from (the original root span). */
+        originalSpanId?: string | null;
+        /** @deprecated alias for `originalTraceId`. */
+        sourceTraceId: string | null;
+        /** @deprecated alias for `originalSpanId`. */
+        sourceSpanId?: string | null;
         /** Deserialized inputs from the original trace. */
         input?: unknown[];
         /** The result returned by the replayed function, or undefined on error. */
@@ -847,9 +878,13 @@ declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
 declare function reportReplayProgress(progress: ReplayProgress): void;
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
-    /** Bitfab trace ID of the historical trace being replayed. */
-    traceId: string;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId: string;
     /** External span ID the recorded inputs were read from. */
+    originalSpanId: string;
+    /** @deprecated alias for {@link AdaptContext.originalTraceId}. */
+    sourceTraceId: string;
+    /** @deprecated alias for {@link AdaptContext.originalSpanId}. */
     sourceSpanId: string;
 }
 /**
@@ -865,8 +900,23 @@ interface AdaptContext {
  */
 type AdaptInputsFn = (inputs: unknown[], ctx: AdaptContext) => unknown[];
 interface ReplayItem<T> {
-    /** Trace ID of the new trace created during replay. */
+    /**
+     * Server trace ID of the new replay trace this item produced. Written in by
+     * `replay()` from the complete-replay response once the server has minted the
+     * trace row; the client-side id used to correlate spans during the run is
+     * never surfaced here. Null until completion, on older servers that omit the
+     * mapping, or if the item produced no trace. Not the verdict-persistence key:
+     * that is the original-trace lineage (`originalTraceId` + `testRunId`).
+     */
     traceId: string | null;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId: string;
+    /** External span ID the recorded inputs were read from (the original root span). */
+    originalSpanId: string;
+    /** @deprecated alias for {@link ReplayItem.originalTraceId}. */
+    sourceTraceId: string;
+    /** @deprecated alias for {@link ReplayItem.originalSpanId}. */
+    sourceSpanId: string;
     /** Deserialized inputs from the original trace. */
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
@@ -1758,7 +1808,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.29.0";
+declare const __version__ = "0.30.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -749,6 +749,15 @@ interface ReplayOptions {
      * reconstructed. Validated server-side against the org.
      */
     datasetId?: string;
+    /**
+     * Graders to attach directly to this experiment (test run), independent of any
+     * graders already on the dataset. The resulting experiment is graded by the
+     * union of these and the dataset's runnable graders at completion, so use this
+     * to grade a single run with a check you don't want to add to the dataset
+     * permanently. Each id must be an active/live grader belonging to the same
+     * organization and trace function, otherwise the server rejects the replay.
+     */
+    graderIds?: string[];
     /**
      * Reshape recorded inputs before they are spread into `fn`.
      *
@@ -785,6 +794,21 @@ interface ReplayOptions {
 }
 /** Running totals reported to {@link ReplayOptions.onProgress} as replay proceeds. */
 interface ReplayProgress {
+    /**
+     * Event kind. Omitted (or `"item"`) for the per-trace settle events streamed
+     * during the run. `"complete"` marks the single terminal event emitted once
+     * the run has settled and been enriched server-side; it carries the full
+     * {@link ReplayProgress.result} and has no `item`. The Bitfab plugin reads
+     * that terminal event to build the run's final result without parsing stdout.
+     */
+    type?: "item" | "complete";
+    /**
+     * The full {@link ReplayResult}, present only on the terminal `"complete"`
+     * event. Lets the plugin ingest the enriched result (server-aggregated tokens,
+     * server trace ids) over the same channel as progress, so a dependency logging
+     * to stdout can never block it.
+     */
+    result?: ReplayResult<unknown>;
     /** Test run ID created for this replay. */
     testRunId?: string;
     /** Items that have finished so far, whether they succeeded or errored. */
@@ -796,18 +820,25 @@ interface ReplayProgress {
     /** Of the completed items, how many threw (their `item.error` is set). */
     errored: number;
     /**
-     * The single item that just settled to produce this event. `traceId` is the
-     * source (historical) trace that was replayed (so a UI can identify or link
-     * it); `error` is its replay error, or null when it ran ok; `durationMs` is how
-     * long this one trace took to replay. Lets a progress UI show per-trace
-     * pass/fail and timing as the run streams, without waiting for the full
-     * {@link ReplayResult}.
+     * The single item that just settled to produce this event. `traceId` is null
+     * at this stage (the server replay id isn't known until the run completes);
+     * `originalTraceId` is the original (historical) trace that was replayed (so
+     * a UI can identify or link it); `error` is its replay error, or null when it
+     * ran ok; `durationMs` is how long this one trace took to replay. Lets a
+     * progress UI show per-trace pass/fail and timing as the run streams, without
+     * waiting for the full {@link ReplayResult}.
      */
     item?: {
-        /** Source (historical) trace ID being replayed. */
-        traceId: string | null;
-        /** Local SDK replay trace ID, before the server maps it to a row ID. */
-        replayTraceId?: string | null;
+        /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
+        traceId?: string | null;
+        /** Bitfab trace ID of the original (historical) trace being replayed. */
+        originalTraceId: string | null;
+        /** External span ID the recorded inputs were read from (the original root span). */
+        originalSpanId?: string | null;
+        /** @deprecated alias for `originalTraceId`. */
+        sourceTraceId: string | null;
+        /** @deprecated alias for `originalSpanId`. */
+        sourceSpanId?: string | null;
         /** Deserialized inputs from the original trace. */
         input?: unknown[];
         /** The result returned by the replayed function, or undefined on error. */
@@ -847,9 +878,13 @@ declare const BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
 declare function reportReplayProgress(progress: ReplayProgress): void;
 /** Per-trace context passed to {@link ReplayOptions.adaptInputs}. */
 interface AdaptContext {
-    /** Bitfab trace ID of the historical trace being replayed. */
-    traceId: string;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId: string;
     /** External span ID the recorded inputs were read from. */
+    originalSpanId: string;
+    /** @deprecated alias for {@link AdaptContext.originalTraceId}. */
+    sourceTraceId: string;
+    /** @deprecated alias for {@link AdaptContext.originalSpanId}. */
     sourceSpanId: string;
 }
 /**
@@ -865,8 +900,23 @@ interface AdaptContext {
  */
 type AdaptInputsFn = (inputs: unknown[], ctx: AdaptContext) => unknown[];
 interface ReplayItem<T> {
-    /** Trace ID of the new trace created during replay. */
+    /**
+     * Server trace ID of the new replay trace this item produced. Written in by
+     * `replay()` from the complete-replay response once the server has minted the
+     * trace row; the client-side id used to correlate spans during the run is
+     * never surfaced here. Null until completion, on older servers that omit the
+     * mapping, or if the item produced no trace. Not the verdict-persistence key:
+     * that is the original-trace lineage (`originalTraceId` + `testRunId`).
+     */
     traceId: string | null;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId: string;
+    /** External span ID the recorded inputs were read from (the original root span). */
+    originalSpanId: string;
+    /** @deprecated alias for {@link ReplayItem.originalTraceId}. */
+    sourceTraceId: string;
+    /** @deprecated alias for {@link ReplayItem.originalSpanId}. */
+    sourceSpanId: string;
     /** Deserialized inputs from the original trace. */
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
@@ -1758,7 +1808,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.29.0";
+declare const __version__ = "0.30.0";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -14,12 +14,12 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-2M5AWVVQ.js";
+} from "./chunk-FHCRK2P6.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   reportReplayProgress
-} from "./chunk-V3XORTWI.js";
+} from "./chunk-2EFKQLJ7.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -394,23 +394,27 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, environment, adaptInputs) {
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, environment, adaptInputs) {
   const lease = environment ? serverItem.dbBranchLease : void 0;
   let inputs = [];
   let originalOutput;
   let result;
   let error = null;
-  const replayedTraceId = randomUuid();
   const pendingPersistence = [];
+  const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
+  const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
   try {
-    const span = await httpClient.getExternalSpan(serverItem.externalSpanId);
+    const span = await httpClient.getExternalSpan(originalSpanId);
     const spanData = span.rawData?.span_data ?? {};
     inputs = deserializeInputs(spanData);
     originalOutput = deserializeOutput(spanData);
     if (adaptInputs) {
       inputs = adaptInputs(inputs, {
-        traceId: serverItem.traceId,
-        sourceSpanId: serverItem.externalSpanId
+        originalTraceId,
+        originalSpanId,
+        // Deprecated aliases for originalTraceId/originalSpanId.
+        sourceTraceId: originalTraceId,
+        sourceSpanId: originalSpanId
       });
     }
     const hasOverrides = resolvedOverrides.length > 0;
@@ -419,15 +423,14 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     let mockTree;
     if (needTree) {
       try {
-        const treeResponse = await httpClient.getSpanTree(
-          serverItem.externalSpanId,
-          { includeOutputs }
-        );
+        const treeResponse = await httpClient.getSpanTree(originalSpanId, {
+          includeOutputs
+        });
         if (treeResponse.root) {
           mockTree = buildMockTree(treeResponse.root);
         } else if (mockStrategy === "all" || hasOverrides) {
           throw new BitfabError(
-            `Replay mock strategy "${mockStrategy}"${hasOverrides ? " with overrides" : ""} requires a span tree root for source span ${serverItem.externalSpanId}.`
+            `Replay mock strategy "${mockStrategy}"${hasOverrides ? " with overrides" : ""} requires a span tree root for original span ${originalSpanId}.`
           );
         } else {
           mockTree = void 0;
@@ -458,7 +461,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         traceId: replayedTraceId,
         inputSourceSpanId: span.id,
         inputSourceTraceId: span.externalTraceId,
-        sourceBitfabTraceId: serverItem.traceId,
+        sourceBitfabTraceId: originalTraceId,
         mockTree,
         callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
         mockStrategy,
@@ -488,7 +491,15 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     }
   }
   return {
-    traceId: replayedTraceId,
+    // Written in by replay() from the complete-replay response once the server
+    // has minted this replay trace's row. Null until then: the client-side
+    // correlation id (replayedTraceId) is never surfaced as the item's traceId.
+    traceId: null,
+    originalTraceId,
+    originalSpanId,
+    // Deprecated aliases for originalTraceId/originalSpanId.
+    sourceTraceId: originalTraceId,
+    sourceSpanId: originalSpanId,
     input: inputs,
     result,
     originalOutput,
@@ -556,7 +567,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     options?.environment !== void 0,
     // includeDbBranchLease
     options?.experimentGroupId,
-    options?.datasetId
+    options?.datasetId,
+    options?.graderIds
   );
   const mockStrategy = options?.mock ?? "marked";
   const maxConcurrency = options?.maxConcurrency ?? 10;
@@ -564,14 +576,16 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
   ];
+  const replayedTraceIds = serverItems.map(() => randomUuid());
   const tasks = serverItems.map(
-    (serverItem) => () => processItem(
+    (serverItem, index) => () => processItem(
       httpClient,
       serverItem,
       fn,
       testRunId,
       mockStrategy,
       resolvedOverrides,
+      replayedTraceIds[index],
       options?.environment,
       options?.adaptInputs
     )
@@ -598,11 +612,17 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
           succeeded,
           errored,
           item: {
-            // Source (historical) trace id, so a UI can identify the trace
-            // that just settled. The item's own traceId is the new replay
-            // trace and is assigned later (below), so use the server item.
-            traceId: serverItems[index]?.traceId ?? null,
-            replayTraceId: item.traceId,
+            // The server replay trace id isn't known until completeReplay
+            // runs (below), so it can't be reported mid-run and we never
+            // emit the client-side placeholder. originalTraceId (the
+            // historical trace) is known now and is what a UI keys on to
+            // identify what just settled.
+            traceId: null,
+            originalTraceId: item.originalTraceId ?? null,
+            originalSpanId: item.originalSpanId ?? null,
+            // Deprecated aliases for originalTraceId/originalSpanId.
+            sourceTraceId: item.originalTraceId ?? null,
+            sourceSpanId: item.originalSpanId ?? null,
             input: item.input,
             result: item.result,
             originalOutput: item.originalOutput,
@@ -620,56 +640,58 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   const completeResult = await httpClient.completeReplay(testRunId);
   const serverTraceIds = completeResult.traceIds;
   const replayTokens = completeResult.tokens;
-  if (serverTraceIds === void 0) {
-    try {
-      console.warn(
-        "Bitfab: server did not return replay trace IDs; item.traceId will be null (server upgrade required for verdict persistence)"
-      );
-    } catch {
-    }
-    for (const item of resultItems) {
-      item.traceId = null;
-    }
-  } else {
+  if (serverTraceIds !== void 0) {
     const missing = [];
     let completedCount = 0;
-    for (const item of resultItems) {
-      if (item.traceId) {
-        const mapped = serverTraceIds[item.traceId];
-        if (item.error === null) {
-          completedCount += 1;
-          if (mapped === void 0) {
-            missing.push(item.traceId);
-          }
-        }
-        if (mapped !== void 0) {
-          item.tokens = replayTokens?.[mapped] ?? null;
+    for (let index = 0; index < resultItems.length; index += 1) {
+      const item = resultItems[index];
+      const localId = replayedTraceIds[index];
+      const mapped = localId ? serverTraceIds[localId] : void 0;
+      item.traceId = mapped ?? null;
+      if (item.error === null) {
+        completedCount += 1;
+        if (mapped === void 0) {
+          missing.push(localId ?? item.originalTraceId);
         }
-        item.traceId = mapped ?? null;
+      }
+      if (mapped !== void 0) {
+        item.tokens = replayTokens?.[mapped] ?? null;
       }
     }
-    if (missing.length > 0) {
+    if (completedCount > 0 && missing.length === completedCount) {
       const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
-      if (missing.length === completedCount) {
-        throw 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.`
-        );
-      }
+      throw 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.`
+      );
+    }
+    if (missing.length > 0) {
       try {
         console.error(
-          `Bitfab: server has no persisted trace for ${missing.length} of ${completedCount} completed replay item(s) (testRunId ${testRunId}).${serverCount} Their traceId is null and verdicts cannot be persisted for them. Missing: ${missing.join(", ")}`
+          `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.`
         );
       } catch {
       }
     }
   }
-  const replayResult = {
+  const result = {
     items: resultItems,
     testRunId,
     testRunUrl: `${serviceUrl}${testRunUrl}`
   };
-  await writeReplayResultFile(replayResult);
-  return replayResult;
+  await writeReplayResultFile(result);
+  try {
+    options?.onProgress?.({
+      type: "complete",
+      testRunId,
+      completed: total,
+      total,
+      succeeded,
+      errored,
+      result
+    });
+  } catch {
+  }
+  return result;
 }
 async function writeReplayResultFile(result) {
   const resultPath = typeof process !== "undefined" ? process.env?.BITFAB_REPLAY_RESULT_PATH : void 0;
@@ -739,7 +761,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.29.0";
+var __version__ = "0.30.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -1098,7 +1120,7 @@ var HttpClient = class {
    * 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) {
+  async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds) {
     const payload = { traceFunctionKey };
     if (limit !== void 0) {
       payload.limit = limit;
@@ -1124,6 +1146,9 @@ var HttpClient = class {
     if (datasetId !== void 0) {
       payload.datasetId = datasetId;
     }
+    if (graderIds !== void 0) {
+      payload.graderIds = graderIds;
+    }
     const timeout = includeDbBranchLease ? 18e4 : 3e4;
     return this.request("/api/sdk/replay/start", payload, {
       timeout
@@ -4169,7 +4194,7 @@ var Bitfab = class {
                   dbSnapshotUsage: {
                     neonBranchId: replayCtx.dbBranchLease.neonBranchId,
                     snapshotTimestamp: replayCtx.dbBranchLease.snapshotTimestamp,
-                    sourceTraceId: replayCtx.sourceBitfabTraceId,
+                    originalTraceId: replayCtx.sourceBitfabTraceId,
                     accessed: replayCtx.dbSnapshotAccessed === true
                   }
                 }
@@ -4473,8 +4498,11 @@ var Bitfab = class {
         ...params.dbSnapshotUsage.snapshotTimestamp && {
           snapshot_timestamp: params.dbSnapshotUsage.snapshotTimestamp
         },
-        ...params.dbSnapshotUsage.sourceTraceId && {
-          source_trace_id: params.dbSnapshotUsage.sourceTraceId
+        ...params.dbSnapshotUsage.originalTraceId && {
+          original_trace_id: params.dbSnapshotUsage.originalTraceId,
+          // Deprecated wire alias, kept so this SDK still reports usage
+          // against servers that predate the rename.
+          source_trace_id: params.dbSnapshotUsage.originalTraceId
         },
         accessed: params.dbSnapshotUsage.accessed
       };