@bitfab/sdk 0.13.8 → 0.15.0

package/dist/index.cjs

@@ -30,25 +30,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/version.generated.ts
-var __version__;
-var init_version_generated = __esm({
-  "src/version.generated.ts"() {
-    "use strict";
-    __version__ = "0.13.8";
-  }
-});
-
-// src/constants.ts
-var DEFAULT_SERVICE_URL;
-var init_constants = __esm({
-  "src/constants.ts"() {
-    "use strict";
-    init_version_generated();
-    DEFAULT_SERVICE_URL = "https://bitfab.ai";
-  }
-});
-
 // src/errors.ts
 var BitfabError;
 var init_errors = __esm({
@@ -64,340 +45,6 @@ var init_errors = __esm({
   }
 });
 
-// src/http.ts
-function awaitOnExit(promise) {
-  pendingTracePromises.add(promise);
-  void promise.finally(() => {
-    pendingTracePromises.delete(promise);
-  }).catch(() => {
-  });
-  return promise;
-}
-async function flushTraces(timeoutMs = 5e3) {
-  if (pendingTracePromises.size === 0) {
-    return;
-  }
-  await Promise.race([
-    Promise.allSettled(Array.from(pendingTracePromises)),
-    new Promise((resolve) => setTimeout(resolve, timeoutMs))
-  ]);
-}
-var pendingTracePromises, HttpClient;
-var init_http = __esm({
-  "src/http.ts"() {
-    "use strict";
-    init_constants();
-    init_errors();
-    pendingTracePromises = /* @__PURE__ */ new Set();
-    if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
-      let isFlushing = false;
-      process.on("beforeExit", () => {
-        if (pendingTracePromises.size > 0 && !isFlushing) {
-          isFlushing = true;
-          Promise.allSettled(
-            Array.from(pendingTracePromises).map(
-              (p) => p.catch(() => {
-              })
-            )
-          ).then(() => {
-            isFlushing = false;
-          }).catch(() => {
-            isFlushing = false;
-          });
-        }
-      });
-    }
-    HttpClient = class {
-      constructor(config) {
-        this.apiKey = config.apiKey;
-        this.serviceUrl = config.serviceUrl;
-        this.timeout = config.timeout ?? 12e4;
-      }
-      /**
-       * Make an HTTP request to the Bitfab API. Defaults to POST; pass
-       * `options.method` to use a different verb (e.g. "PATCH").
-       *
-       * @param endpoint - The API endpoint (without base URL)
-       * @param payload - The request body
-       * @param options - Optional request options
-       * @returns The parsed JSON response
-       * @throws {BitfabError} If the request fails
-       */
-      async request(endpoint, payload, options) {
-        const url = `${this.serviceUrl}${endpoint}`;
-        const timeout = options?.timeout ?? this.timeout;
-        const method = options?.method ?? "POST";
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeout);
-        let body;
-        let serializationError;
-        try {
-          body = JSON.stringify(payload);
-        } catch (error) {
-          serializationError = error instanceof Error ? error.message : String(error);
-          body = JSON.stringify({
-            ...Object.fromEntries(
-              Object.entries(payload).filter(
-                ([, v]) => typeof v === "string" || typeof v === "number"
-              )
-            ),
-            rawSpan: {},
-            errors: [
-              { source: "sdk", step: "json_serialize", error: serializationError }
-            ]
-          });
-        }
-        try {
-          const response = await fetch(url, {
-            method,
-            headers: {
-              "Content-Type": "application/json",
-              Authorization: `Bearer ${this.apiKey}`
-            },
-            body,
-            signal: controller.signal
-          });
-          if (!response.ok) {
-            const errorText = await response.text();
-            throw new BitfabError(
-              `HTTP ${response.status}: ${errorText.slice(0, 500)}`
-            );
-          }
-          const result = await response.json();
-          if (result.error) {
-            if (result.url) {
-              throw new BitfabError(
-                `${result.error} Configure it at: ${this.serviceUrl}${result.url}`,
-                result.url
-              );
-            }
-            throw new BitfabError(result.error);
-          }
-          return result;
-        } catch (error) {
-          if (error instanceof BitfabError) {
-            throw error;
-          }
-          if (error instanceof Error) {
-            if (error.name === "AbortError") {
-              throw new BitfabError(`Request timed out after ${timeout}ms`);
-            }
-            throw new BitfabError(error.message);
-          }
-          throw new BitfabError("Unknown error occurred");
-        } finally {
-          clearTimeout(timeoutId);
-        }
-      }
-      /**
-       * Look up a function by name.
-       * Blocks until complete - needed for function execution.
-       */
-      async lookupFunction(name) {
-        return this.request("/api/sdk/functions/lookup", { name });
-      }
-      /**
-       * Send an internal trace (from BAML execution).
-       * Fire-and-forget with awaitOnExit - doesn't block the caller.
-       */
-      sendInternalTrace(functionId, payload) {
-        void awaitOnExit(
-          this.request(`/api/sdk/functions/${functionId}/traces`, {
-            ...payload,
-            sdkVersion: __version__
-          })
-        ).catch((error) => {
-          try {
-            console.error("Bitfab: Failed to create trace:", error);
-          } catch {
-          }
-        });
-      }
-      /**
-       * Send an external span (from withSpan wrapper or OpenAI tracing).
-       * Fire-and-forget with awaitOnExit - doesn't block the caller.
-       * Returns the tracked promise so callers can optionally await it.
-       */
-      sendExternalSpan(payload) {
-        return awaitOnExit(
-          this.request("/api/sdk/externalSpans", {
-            ...payload,
-            sdkVersion: __version__
-          })
-        ).catch((error) => {
-          try {
-            console.error("Bitfab: Failed to create external span:", error);
-          } catch {
-          }
-        });
-      }
-      /**
-       * Send an external trace (from OpenAI tracing).
-       * Fire-and-forget with awaitOnExit - doesn't block the caller.
-       */
-      sendExternalTrace(payload) {
-        void awaitOnExit(
-          this.request("/api/sdk/externalTraces", {
-            ...payload,
-            sdkVersion: __version__
-          })
-        ).catch((error) => {
-          try {
-            console.error("Bitfab: Failed to create external trace:", error);
-          } catch {
-          }
-        });
-      }
-      /**
-       * Partial update of an existing external trace identified by sourceTraceId.
-       * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
-       * returns a tracked promise that callers may optionally await.
-       */
-      patchTrace(sourceTraceId, payload) {
-        const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
-        return awaitOnExit(
-          this.request(endpoint, payload, { method: "PATCH" })
-        ).catch((error) => {
-          try {
-            console.error("Bitfab: Failed to patch trace:", error);
-          } catch {
-          }
-        });
-      }
-      /**
-       * Start a replay session by fetching historical traces.
-       * Blocking call — creates a test run and returns lightweight item references.
-       */
-      async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId) {
-        const payload = { traceFunctionKey, limit };
-        if (traceIds) {
-          payload.traceIds = traceIds;
-        }
-        if (codeChangeDescription !== void 0) {
-          payload.codeChangeDescription = codeChangeDescription;
-        }
-        if (codeChangeFiles !== void 0) {
-          payload.codeChangeFiles = codeChangeFiles;
-        }
-        if (includeDbBranchLease) {
-          payload.includeDbBranchLease = true;
-        }
-        if (experimentGroupId !== void 0) {
-          payload.experimentGroupId = experimentGroupId;
-        }
-        const timeout = includeDbBranchLease ? 18e4 : 3e4;
-        return this.request("/api/sdk/replay/start", payload, {
-          timeout
-        });
-      }
-      /**
-       * Fetch an external span by ID.
-       * Blocking GET request.
-       */
-      async getExternalSpan(spanId) {
-        const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}`;
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 3e4);
-        try {
-          const response = await fetch(url, {
-            method: "GET",
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-            signal: controller.signal
-          });
-          if (!response.ok) {
-            const errorText = await response.text();
-            throw new BitfabError(
-              `HTTP ${response.status}: ${errorText.slice(0, 500)}`
-            );
-          }
-          return await response.json();
-        } catch (error) {
-          if (error instanceof BitfabError) {
-            throw error;
-          }
-          if (error instanceof Error) {
-            if (error.name === "AbortError") {
-              throw new BitfabError("Request timed out after 30000ms");
-            }
-            throw new BitfabError(error.message);
-          }
-          throw new BitfabError("Unknown error occurred");
-        } finally {
-          clearTimeout(timeoutId);
-        }
-      }
-      /**
-       * Fetch the span tree for a root span.
-       * Blocking GET request.
-       */
-      async getSpanTree(externalSpanId) {
-        const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`;
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 3e4);
-        try {
-          const response = await fetch(url, {
-            method: "GET",
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-            signal: controller.signal
-          });
-          if (!response.ok) {
-            const errorText = await response.text();
-            throw new BitfabError(
-              `HTTP ${response.status}: ${errorText.slice(0, 500)}`
-            );
-          }
-          return await response.json();
-        } catch (error) {
-          if (error instanceof BitfabError) {
-            throw error;
-          }
-          if (error instanceof Error) {
-            if (error.name === "AbortError") {
-              throw new BitfabError("Request timed out after 30000ms");
-            }
-            throw new BitfabError(error.message);
-          }
-          throw new BitfabError("Unknown error occurred");
-        } finally {
-          clearTimeout(timeoutId);
-        }
-      }
-      /**
-       * Mark a replay test run as completed.
-       * Blocking call.
-       */
-      async completeReplay(testRunId) {
-        return this.request(
-          "/api/sdk/replay/complete",
-          { testRunId },
-          { timeout: 3e4 }
-        );
-      }
-      /**
-       * Ask the server to materialize a per-trace DB branch lease from a
-       * captured `dbSnapshotRef`. Blocking — the resolver creates a Neon
-       * snapshot + preview branch and polls operations to readiness, which
-       * can take seconds.
-       */
-      async resolveDbBranchLease(testRunId, traceId, dbSnapshotRef) {
-        return this.request(
-          "/api/sdk/replay/resolveDbBranchLease",
-          { testRunId, traceId, dbSnapshotRef },
-          { timeout: 9e4 }
-        );
-      }
-      /** Release a previously-resolved DB branch by deleting its Neon branch. Idempotent server-side. */
-      async releaseDbBranchLease(neonBranchId) {
-        await this.request(
-          "/api/sdk/replay/releaseDbBranchLease",
-          { neonBranchId },
-          { timeout: 3e4 }
-        );
-      }
-    };
-  }
-});
-
 // src/asyncStorage.ts
 function registerAsyncLocalStorageClass(cls) {
   if (!AsyncLocalStorageClass) {
@@ -578,6 +225,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
   let result;
   let error = null;
   const replayedTraceId = crypto.randomUUID();
+  const pendingPersistence = [];
   try {
     const span = await httpClient.getExternalSpan(serverItem.externalSpanId);
     const spanData = span.rawData?.span_data ?? {};
@@ -600,7 +248,8 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
         mockTree,
         callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
         mockStrategy,
-        dbBranchLease: lease
+        dbBranchLease: lease,
+        pendingPersistence
       },
       () => fn(...inputs)
     );
@@ -608,6 +257,7 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
   } catch (e) {
     error = e instanceof Error ? e.message : String(e);
   } finally {
+    await Promise.allSettled(pendingPersistence);
     if (lease) {
       try {
         await httpClient.releaseDbBranchLease(lease.neonBranchId);
@@ -650,6 +300,21 @@ async function mapWithConcurrency(tasks, maxConcurrency) {
   return results;
 }
 async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
+  if (options?.traceIds !== void 0) {
+    if (options.traceIds.length === 0) {
+      throw new BitfabError("traceIds must contain at least one trace ID.");
+    }
+    if (options.traceIds.length > 100) {
+      throw new BitfabError(
+        `traceIds supports at most 100 trace IDs per replay (got ${options.traceIds.length}).`
+      );
+    }
+  }
+  if (options?.limit !== void 0 && options?.traceIds !== void 0) {
+    throw new BitfabError(
+      "Pass either limit or traceIds, not both: an explicit trace ID list already determines how many traces replay."
+    );
+  }
   await replayContextReady;
   const {
     testRunId,
@@ -657,7 +322,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     items: serverItems
   } = await httpClient.startReplay(
     traceFunctionKey,
-    options?.limit ?? 5,
+    // limit is meaningless with explicit traceIds (the ID list determines
+    // the count), so it's omitted from the request entirely.
+    options?.traceIds ? void 0 : options?.limit ?? 5,
     options?.traceIds,
     options?.codeChangeDescription,
     options?.codeChangeFiles,
@@ -678,20 +345,46 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     )
   );
   const resultItems = await mapWithConcurrency(tasks, maxConcurrency);
-  await flushTraces();
-  let serverTraceIds = {};
-  try {
-    const completeResult = await httpClient.completeReplay(testRunId);
-    serverTraceIds = completeResult.traceIds ?? {};
-  } catch (e) {
+  const completeResult = await httpClient.completeReplay(testRunId);
+  const serverTraceIds = completeResult.traceIds;
+  if (serverTraceIds === void 0) {
     try {
-      console.error("Bitfab: Failed to complete replay:", e);
+      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) {
-    if (item.traceId) {
-      item.traceId = serverTraceIds[item.traceId] ?? null;
+    for (const item of resultItems) {
+      item.traceId = null;
+    }
+  } else {
+    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);
+          }
+        }
+        item.traceId = mapped ?? null;
+      }
+    }
+    if (missing.length > 0) {
+      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.`
+        );
+      }
+      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(", ")}`
+        );
+      } catch {
+      }
     }
   }
   return {
@@ -703,7 +396,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
-    init_http();
+    init_errors();
     init_replayContext();
     init_serialize();
   }
@@ -728,9 +421,346 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/version.generated.ts
+var __version__ = "0.15.0";
+
+// src/constants.ts
+var DEFAULT_SERVICE_URL = "https://bitfab.ai";
+
+// src/http.ts
+init_errors();
+var pendingTracePromises = /* @__PURE__ */ new Set();
+function awaitOnExit(promise) {
+  pendingTracePromises.add(promise);
+  void promise.finally(() => {
+    pendingTracePromises.delete(promise);
+  }).catch(() => {
+  });
+  return promise;
+}
+async function flushTraces(timeoutMs = 5e3) {
+  if (pendingTracePromises.size === 0) {
+    return;
+  }
+  await Promise.race([
+    Promise.allSettled(Array.from(pendingTracePromises)),
+    new Promise((resolve) => setTimeout(resolve, timeoutMs))
+  ]);
+}
+if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
+  let isFlushing = false;
+  process.on("beforeExit", () => {
+    if (pendingTracePromises.size > 0 && !isFlushing) {
+      isFlushing = true;
+      Promise.allSettled(
+        Array.from(pendingTracePromises).map(
+          (p) => p.catch(() => {
+          })
+        )
+      ).then(() => {
+        isFlushing = false;
+      }).catch(() => {
+        isFlushing = false;
+      });
+    }
+  });
+}
+var HttpClient = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.serviceUrl = config.serviceUrl;
+    this.timeout = config.timeout ?? 12e4;
+  }
+  /**
+   * Make an HTTP request to the Bitfab API. Defaults to POST; pass
+   * `options.method` to use a different verb (e.g. "PATCH").
+   *
+   * @param endpoint - The API endpoint (without base URL)
+   * @param payload - The request body
+   * @param options - Optional request options
+   * @returns The parsed JSON response
+   * @throws {BitfabError} If the request fails
+   */
+  async request(endpoint, payload, options) {
+    const url = `${this.serviceUrl}${endpoint}`;
+    const timeout = options?.timeout ?? this.timeout;
+    const method = options?.method ?? "POST";
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    let body;
+    let serializationError;
+    try {
+      body = JSON.stringify(payload);
+    } catch (error) {
+      serializationError = error instanceof Error ? error.message : String(error);
+      body = JSON.stringify({
+        ...Object.fromEntries(
+          Object.entries(payload).filter(
+            ([, v]) => typeof v === "string" || typeof v === "number"
+          )
+        ),
+        rawSpan: {},
+        errors: [
+          { source: "sdk", step: "json_serialize", error: serializationError }
+        ]
+      });
+    }
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      const result = await response.json();
+      if (result.error) {
+        if (result.url) {
+          throw new BitfabError(
+            `${result.error} Configure it at: ${this.serviceUrl}${result.url}`,
+            result.url
+          );
+        }
+        throw new BitfabError(result.error);
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError(`Request timed out after ${timeout}ms`);
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Look up a function by name.
+   * Blocks until complete - needed for function execution.
+   */
+  async lookupFunction(name) {
+    return this.request("/api/sdk/functions/lookup", { name });
+  }
+  /**
+   * Send an internal trace (from BAML execution).
+   * Fire-and-forget with awaitOnExit - doesn't block the caller.
+   */
+  sendInternalTrace(functionId, payload) {
+    void awaitOnExit(
+      this.request(`/api/sdk/functions/${functionId}/traces`, {
+        ...payload,
+        sdkVersion: __version__
+      })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to create trace:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Send an external span (from withSpan wrapper or OpenAI tracing).
+   * Fire-and-forget with awaitOnExit - doesn't block the caller.
+   * Returns the tracked promise so callers can optionally await it.
+   */
+  sendExternalSpan(payload) {
+    return awaitOnExit(
+      this.request("/api/sdk/externalSpans", {
+        ...payload,
+        sdkVersion: __version__
+      })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to create external span:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Send an external trace (from OpenAI tracing).
+   * Fire-and-forget with awaitOnExit - doesn't block the caller.
+   * Returns the tracked promise so callers can optionally await it
+   * (the replay path does, so trace completions are persisted before
+   * `completeReplay` builds the trace-ID mapping).
+   */
+  sendExternalTrace(payload) {
+    return awaitOnExit(
+      this.request("/api/sdk/externalTraces", {
+        ...payload,
+        sdkVersion: __version__
+      })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to create external trace:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Partial update of an existing external trace identified by sourceTraceId.
+   * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
+   * returns a tracked promise that callers may optionally await.
+   */
+  patchTrace(sourceTraceId, payload) {
+    const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
+    return awaitOnExit(
+      this.request(endpoint, payload, { method: "PATCH" })
+    ).catch((error) => {
+      try {
+        console.error("Bitfab: Failed to patch trace:", error);
+      } catch {
+      }
+    });
+  }
+  /**
+   * Start a replay session by fetching historical traces.
+   * Blocking call — creates a test run and returns lightweight item references.
+   */
+  async startReplay(traceFunctionKey, limit, traceIds, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId) {
+    const payload = { traceFunctionKey };
+    if (limit !== void 0) {
+      payload.limit = limit;
+    }
+    if (traceIds) {
+      payload.traceIds = traceIds;
+    }
+    if (codeChangeDescription !== void 0) {
+      payload.codeChangeDescription = codeChangeDescription;
+    }
+    if (codeChangeFiles !== void 0) {
+      payload.codeChangeFiles = codeChangeFiles;
+    }
+    if (includeDbBranchLease) {
+      payload.includeDbBranchLease = true;
+    }
+    if (experimentGroupId !== void 0) {
+      payload.experimentGroupId = experimentGroupId;
+    }
+    const timeout = includeDbBranchLease ? 18e4 : 3e4;
+    return this.request("/api/sdk/replay/start", payload, {
+      timeout
+    });
+  }
+  /**
+   * Fetch an external span by ID.
+   * Blocking GET request.
+   */
+  async getExternalSpan(spanId) {
+    const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError("Request timed out after 30000ms");
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Fetch the span tree for a root span.
+   * Blocking GET request.
+   */
+  async getSpanTree(externalSpanId) {
+    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError("Request timed out after 30000ms");
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Mark a replay test run as completed.
+   * Blocking call.
+   */
+  async completeReplay(testRunId) {
+    return this.request(
+      "/api/sdk/replay/complete",
+      { testRunId },
+      { timeout: 3e4 }
+    );
+  }
+  /**
+   * Ask the server to materialize a per-trace DB branch lease from a
+   * captured `dbSnapshotRef`. Blocking — the resolver creates a Neon
+   * snapshot + preview branch and polls operations to readiness, which
+   * can take seconds.
+   */
+  async resolveDbBranchLease(testRunId, traceId, dbSnapshotRef) {
+    return this.request(
+      "/api/sdk/replay/resolveDbBranchLease",
+      { testRunId, traceId, dbSnapshotRef },
+      { timeout: 9e4 }
+    );
+  }
+  /** Release a previously-resolved DB branch by deleting its Neon branch. Idempotent server-side. */
+  async releaseDbBranchLease(neonBranchId) {
+    await this.request(
+      "/api/sdk/replay/releaseDbBranchLease",
+      { neonBranchId },
+      { timeout: 3e4 }
+    );
+  }
+};
+
 // src/claudeAgentSdk.ts
-init_constants();
-init_http();
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
@@ -1495,9 +1525,6 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
   };
 }
 
-// src/client.ts
-init_constants();
-
 // src/dbSnapshot.ts
 init_errors();
 var SUPPORTED_PROVIDERS = ["neon"];
@@ -1515,12 +1542,7 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
   };
 }
 
-// src/client.ts
-init_http();
-
 // src/langgraph.ts
-init_constants();
-init_http();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
 var LANGGRAPH_METADATA_KEYS = [
   "langgraph_step",
@@ -2068,8 +2090,6 @@ var ReplayEnvironment = class {
 init_serialize();
 
 // src/tracing.ts
-init_constants();
-init_http();
 var BitfabOpenAITracingProcessor = class {
   /**
    * Initialize the tracing processor.
@@ -2903,9 +2923,18 @@ var Bitfab = class {
         spanType: options.type ?? "custom"
       };
       const sendSpan = async (params) => {
+        const replayCtx = getReplayContext();
+        const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
+        let resolvePersistence;
+        if (persistenceCollector) {
+          persistenceCollector.push(
+            new Promise((resolve) => {
+              resolvePersistence = resolve;
+            })
+          );
+        }
         try {
           const endedAt = (/* @__PURE__ */ new Date()).toISOString();
-          const replayCtx = getReplayContext();
           const spanPromise = self.sendWrapperSpan({
             ...baseSpanParams,
             ...params,
@@ -2920,13 +2949,17 @@ var Bitfab = class {
           if (isRootSpan) {
             const pending = pendingSpanPromises.get(traceId) ?? [];
             pending.push(spanPromise);
-            await Promise.race([
-              Promise.allSettled(pending),
-              new Promise((resolve) => setTimeout(resolve, 5e3))
-            ]);
+            if (persistenceCollector) {
+              await Promise.allSettled(pending);
+            } else {
+              await Promise.race([
+                Promise.allSettled(pending),
+                new Promise((resolve) => setTimeout(resolve, 5e3))
+              ]);
+            }
             pendingSpanPromises.delete(traceId);
             const traceState = activeTraceStates.get(traceId);
-            self.sendTraceCompletion({
+            const completionPromise = self.sendTraceCompletion({
               traceFunctionKey,
               traceId,
               startedAt: traceState?.startedAt ?? startedAt,
@@ -2939,6 +2972,9 @@ var Bitfab = class {
               dbSnapshotRef: traceState?.dbSnapshotRef
             });
             activeTraceStates.delete(traceId);
+            if (persistenceCollector) {
+              await completionPromise;
+            }
           } else {
             const pending = pendingSpanPromises.get(traceId);
             if (pending) {
@@ -2948,6 +2984,8 @@ var Bitfab = class {
             }
           }
         } catch {
+        } finally {
+          resolvePersistence?.();
         }
       };
       const replayCtxForMock = getReplayContext();
@@ -3100,7 +3138,7 @@ var Bitfab = class {
     if (params.dbSnapshotRef) {
       rawTrace.db_snapshot_ref = params.dbSnapshotRef;
     }
-    this.httpClient.sendExternalTrace({
+    return this.httpClient.sendExternalTrace({
       type: "sdk-function",
       source: "typescript-sdk-function",
       traceFunctionKey: params.traceFunctionKey,
@@ -3174,7 +3212,9 @@ var Bitfab = class {
    *
    * @param traceFunctionKey - The trace function key to replay
    * @param fn - The function to replay (must be the return value of `withSpan`)
-   * @param options - Optional replay options (limit, traceIds)
+   * @param options - Optional replay options. `limit` and `traceIds` are
+   *   mutually exclusive — an explicit ID list already determines how many
+   *   traces replay, so passing both throws a BitfabError.
    * @returns ReplayResult with items, testRunId, and testRunUrl
    */
   async replay(traceFunctionKey, fn, options) {
@@ -3242,10 +3282,6 @@ var BitfabFunction = class {
     );
   }
 };
-
-// src/index.ts
-init_constants();
-init_http();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Bitfab,