@bitfab/sdk 0.33.6 → 0.34.0

package/dist/index.cjs

@@ -37,219 +37,41 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 
+// src/version.generated.ts
+var __version__;
+var init_version_generated = __esm({
+  "src/version.generated.ts"() {
+    "use strict";
+    __version__ = "0.34.0";
+  }
+});
+
+// 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({
   "src/errors.ts"() {
     "use strict";
     BitfabError = class extends Error {
-      constructor(message, url) {
+      constructor(message, url, status) {
         super(message);
         this.url = url;
+        this.status = status;
         this.name = "BitfabError";
       }
     };
   }
 });
 
-// src/warnOnce.ts
-function warnOnce(key, message) {
-  if (warned.has(key)) {
-    return;
-  }
-  warned.add(key);
-  try {
-    console.warn(`[bitfab] ${message}`);
-  } catch {
-  }
-}
-var warned;
-var init_warnOnce = __esm({
-  "src/warnOnce.ts"() {
-    "use strict";
-    warned = /* @__PURE__ */ new Set();
-  }
-});
-
-// src/serialize.ts
-function describeValue(value) {
-  try {
-    const ctorName = value?.constructor?.name;
-    if (ctorName && ctorName !== "Object") {
-      return ctorName;
-    }
-  } catch {
-  }
-  return typeof value;
-}
-function unserializableStub(value, reason) {
-  warnOnce(
-    `serialize:${reason.replace(/\d+/g, "N")}`,
-    `a value could not be fully serialized for a span (${reason}); it was replaced with a placeholder. The span still ships, but its captured input/output is incomplete.`
-  );
-  let summary;
-  try {
-    summary = `<unserializable: ${describeValue(value)} (${reason})>`;
-  } catch {
-    summary = `<unserializable (${reason})>`;
-  }
-  return { json: summary };
-}
-function serializeValue(value) {
-  try {
-    const { json, meta } = import_superjson.default.serialize(value);
-    let size;
-    try {
-      size = JSON.stringify(json).length;
-    } catch {
-      return unserializableStub(value, "stringify_failed_after_superjson");
-    }
-    if (size > MAX_SERIALIZED_BYTES) {
-      return unserializableStub(value, `too_large_${size}_bytes`);
-    }
-    return meta ? { json, meta } : { json };
-  } catch {
-    try {
-      return { json: JSON.parse(JSON.stringify(value)) };
-    } catch {
-      return unserializableStub(value, "json_stringify_failed");
-    }
-  }
-}
-function deserializeValue(serialized) {
-  if (serialized.meta === void 0) {
-    return serialized.json;
-  }
-  return import_superjson.default.deserialize({
-    json: serialized.json,
-    meta: serialized.meta
-  });
-}
-function toJsonSafe(value) {
-  return toJsonSafeReport(value).safe;
-}
-function toJsonSafeReport(value) {
-  const dropped = [];
-  const safe = toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet(), dropped);
-  try {
-    const size = JSON.stringify(safe)?.length ?? 0;
-    if (size > MAX_FRAMEWORK_SERIALIZED_BYTES) {
-      warnOnce(
-        "toJsonSafe:too_large",
-        `a framework payload exceeded ${MAX_FRAMEWORK_SERIALIZED_BYTES} bytes and was replaced with a placeholder so the span still ships. The captured state for this span is incomplete.`
-      );
-      return {
-        safe: `<unserializable: too_large_${size}_bytes>`,
-        dropped: [...dropped, `too_large_${size}_bytes`]
-      };
-    }
-  } catch {
-  }
-  return { safe, dropped };
-}
-function toJsonSafeInner(value, depth, seen, dropped) {
-  if (value === null || value === void 0) {
-    return value;
-  }
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return value;
-  }
-  const className = value?.constructor?.name ?? typeof value;
-  if (depth > MAX_SAFE_DEPTH) {
-    dropped.push(className);
-    return `<${className}>`;
-  }
-  if (typeof value !== "object") {
-    if (typeof value === "function" || typeof value === "symbol") {
-      dropped.push(className);
-    }
-    try {
-      return String(value);
-    } catch {
-      dropped.push(className);
-      return `<${className}>`;
-    }
-  }
-  if (seen.has(value)) {
-    dropped.push(className);
-    return `<cycle ${className}>`;
-  }
-  seen.add(value);
-  let result;
-  if (Array.isArray(value)) {
-    result = value.map(
-      (item) => toJsonSafeInner(item, depth + 1, seen, dropped)
-    );
-  } else if (typeof value.toJSON === "function") {
-    try {
-      result = toJsonSafeInner(
-        value.toJSON(),
-        depth + 1,
-        seen,
-        dropped
-      );
-    } catch {
-      dropped.push(className);
-      result = `<${className}>`;
-    }
-  } else {
-    try {
-      const obj = {};
-      for (const [k, v] of Object.entries(value)) {
-        if (!k.startsWith("_")) {
-          obj[k] = toJsonSafeInner(v, depth + 1, seen, dropped);
-        }
-      }
-      result = obj;
-    } catch {
-      dropped.push(className);
-      result = `<${className}>`;
-    }
-  }
-  seen.delete(value);
-  return result;
-}
-var import_superjson, MAX_SERIALIZED_BYTES, MAX_FRAMEWORK_SERIALIZED_BYTES, MAX_SAFE_DEPTH;
-var init_serialize = __esm({
-  "src/serialize.ts"() {
-    "use strict";
-    import_superjson = __toESM(require("superjson"), 1);
-    init_warnOnce();
-    MAX_SERIALIZED_BYTES = 512e3;
-    MAX_FRAMEWORK_SERIALIZED_BYTES = 2e6;
-    MAX_SAFE_DEPTH = 6;
-  }
-});
-
-// src/randomUuid.ts
-function randomUuid() {
-  const globalCrypto = globalThis.crypto;
-  if (typeof globalCrypto?.randomUUID === "function") {
-    try {
-      return globalCrypto.randomUUID();
-    } catch {
-    }
-  }
-  warnOnce(
-    "crypto-unavailable",
-    "global crypto.randomUUID is unavailable; using a non-cryptographic fallback for trace/span ids. Tracing works normally (ids are correlation-only, not security-sensitive)."
-  );
-  return fallbackUuidV4();
-}
-function fallbackUuidV4() {
-  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
-    const rand = Math.random() * 16 | 0;
-    const value = char === "x" ? rand : rand & 3 | 8;
-    return value.toString(16);
-  });
-}
-var init_randomUuid = __esm({
-  "src/randomUuid.ts"() {
-    "use strict";
-    init_warnOnce();
-  }
-});
-
 // src/asyncStorage.ts
 function registerAsyncLocalStorageClass(cls) {
   if (!AsyncLocalStorageClass) {
@@ -289,22 +111,6 @@ var init_asyncStorage = __esm({
   }
 });
 
-// src/mockOverride.ts
-function resolveMockValue(value, ctx) {
-  return typeof value === "function" ? value(ctx) : value;
-}
-function normalizeMockOverrides(mockOverride) {
-  if (mockOverride === void 0) {
-    return [];
-  }
-  return Array.isArray(mockOverride) ? mockOverride : [mockOverride];
-}
-var init_mockOverride = __esm({
-  "src/mockOverride.ts"() {
-    "use strict";
-  }
-});
-
 // src/replayContext.ts
 function getReplayContext() {
   return replayContextStorage?.getStore() ?? null;
@@ -338,1184 +144,2306 @@ var init_replayContext = __esm({
   }
 });
 
-// src/codeChange.ts
-async function resolveAutoCodeChange(label) {
-  if (typeof process === "undefined") {
-    return null;
-  }
-  if (process.env?.BITFAB_DISABLE_CODE_CHANGE_CAPTURE) {
-    return null;
+// src/warnOnce.ts
+function warnOnce(key, message) {
+  if (warned.has(key)) {
+    return;
   }
-  const fromEnv = await readCodeChangeFile();
-  if (fromEnv) {
-    return fromEnv;
+  warned.add(key);
+  try {
+    console.warn(`[bitfab] ${message}`);
+  } catch {
   }
-  return captureCodeChangeFromGit(process.cwd?.() ?? ".", label);
 }
-async function readCodeChangeFile() {
-  const path = process.env?.BITFAB_CODE_CHANGE_PATH;
-  if (!path) {
-    return null;
+var warned;
+var init_warnOnce = __esm({
+  "src/warnOnce.ts"() {
+    "use strict";
+    warned = /* @__PURE__ */ new Set();
   }
+});
+
+// src/serializePayload.ts
+function serializePayloadBody(payload) {
   try {
-    const { readFile } = await import("fs/promises");
-    const parsed = JSON.parse(await readFile(path, "utf8"));
-    const files = Array.isArray(parsed?.files) && parsed.files.every(
-      (f) => typeof f === "object" && f !== null && !Array.isArray(f)
-    ) ? parsed.files : void 0;
-    const description = typeof parsed?.description === "string" ? parsed.description : void 0;
-    if (!files && description === void 0) {
-      return null;
-    }
-    return { description, files };
-  } catch {
-    return null;
-  }
-}
-async function captureCodeChangeFromGit(cwd, label) {
-  let execFile;
-  let readFile;
-  try {
-    ;
-    ({ execFile } = await import("child_process"));
-    ({ readFile } = await import("fs/promises"));
+    return { body: JSON.stringify(payload), dropped: [] };
   } catch {
-    return null;
-  }
-  const git = (dir, args) => new Promise((resolve) => {
-    execFile(
-      "git",
-      args,
-      // 30s timeout so a hung git (e.g. a network-touching ref op) can't
-      // block the whole replay indefinitely.
-      { cwd: dir, maxBuffer: 64 * 1024 * 1024, timeout: 3e4 },
-      (err, stdout) => resolve(err ? null : stdout)
-    );
-  });
-  try {
-    const root = (await git(cwd, ["rev-parse", "--show-toplevel"]))?.trim();
-    if (!root) {
-      return null;
-    }
-    const resolved = await resolveBase(git, root);
-    if (!resolved) {
-      return null;
-    }
-    const { base, fromTrunk } = resolved;
-    const blobBytes = async (ref, path) => {
-      const out = await git(root, ["cat-file", "-s", `${ref}:${path}`]);
-      const n = out ? Number.parseInt(out.trim(), 10) : Number.NaN;
-      return Number.isFinite(n) ? n : 0;
-    };
-    const workingBytes = async (path) => {
-      try {
-        const { stat } = await import("fs/promises");
-        const { join } = await import("path");
-        return (await stat(join(root, path))).size;
-      } catch {
-        return 0;
+    const dropped = [];
+    const sanitize = (value, seen) => {
+      const t = typeof value;
+      if (value === null || t === "string" || t === "number" || t === "boolean") {
+        return value;
       }
-    };
-    const tracked = await git(root, [
-      "diff",
-      "--name-status",
-      "--no-renames",
-      "-z",
-      base,
-      "--",
-      ":!.bitfab"
-    ]);
-    const untracked = await git(root, [
-      "ls-files",
-      "--others",
-      "--exclude-standard",
-      "-z",
-      "--",
-      ":!.bitfab"
-    ]);
-    const entries = [
-      ...parseNameStatusZ(tracked ?? ""),
-      ...(untracked ?? "").split(NUL).filter((p) => p.length > 0).map((path) => ({ status: "A", path }))
-    ];
-    if (entries.length === 0) {
-      return null;
-    }
-    const files = [];
-    let totalBytes = 0;
-    for (const { status, path } of entries) {
-      if (files.length >= MAX_FILES) {
-        break;
+      if (t === "bigint") {
+        dropped.push("BigInt");
+        return "<unserializable: BigInt>";
       }
-      const beforeBytes = status === "A" ? 0 : await blobBytes(base, path);
-      const afterBytes = status === "D" ? 0 : await workingBytes(path);
-      if (beforeBytes > MAX_FILE_BYTES || afterBytes > MAX_FILE_BYTES) {
-        continue;
+      if (t === "function") {
+        const name = value.name || "Function";
+        dropped.push(name);
+        return `<unserializable: ${name}>`;
       }
-      const before = (status === "A" ? "" : await git(root, ["show", `${base}:${path}`]) ?? "").replace(/\r\n/g, "\n");
-      const after = (status === "D" ? "" : await readWorkingFile(readFile, root, path)).replace(/\r\n/g, "\n");
-      if (before === after) {
-        continue;
+      if (t === "symbol") {
+        dropped.push("Symbol");
+        return "<unserializable: Symbol>";
       }
-      const size = Buffer.byteLength(before, "utf8") + Buffer.byteLength(after, "utf8");
-      if (totalBytes + size > MAX_TOTAL_BYTES || looksBinary(before) || looksBinary(after)) {
-        continue;
+      if (t !== "object") {
+        return void 0;
       }
-      totalBytes += size;
-      files.push({ path, before, after });
+      const obj = value;
+      const className = obj.constructor?.name || "object";
+      if (seen.has(obj)) {
+        dropped.push(className);
+        return `<cycle: ${className}>`;
+      }
+      seen.add(obj);
+      let result;
+      if (Array.isArray(obj)) {
+        result = obj.map((item) => sanitize(item, seen));
+      } else if (typeof obj.toJSON === "function") {
+        try {
+          result = sanitize(obj.toJSON(), seen);
+        } catch {
+          dropped.push(className);
+          result = `<unserializable: ${className}>`;
+        }
+      } else {
+        try {
+          const out = {};
+          for (const [k, v] of Object.entries(obj)) {
+            out[k] = sanitize(v, seen);
+          }
+          result = out;
+        } catch {
+          warnOnce(
+            "payload:field-getter-threw",
+            "a value with a throwing getter/proxy could not be serialized into a span payload; it was replaced with a placeholder. The span still ships with its other fields intact."
+          );
+          dropped.push(className);
+          result = `<unserializable: ${className}>`;
+        }
+      }
+      seen.delete(obj);
+      return result;
+    };
+    let sanitized;
+    try {
+      sanitized = sanitize(payload, /* @__PURE__ */ new WeakSet());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        body: JSON.stringify({ error: `payload_serialize_failed: ${message}` }),
+        dropped
+      };
     }
-    if (files.length === 0) {
-      return null;
+    if (dropped.length > 0 && typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)) {
+      const obj = sanitized;
+      const existing = Array.isArray(obj.errors) ? obj.errors : [];
+      obj.errors = [
+        ...existing,
+        {
+          source: "sdk",
+          step: "json_serialize",
+          error: `stubbed non-serializable value(s): ${[
+            ...new Set(dropped)
+          ].join(", ")}`
+        }
+      ];
     }
-    const subject = (await git(root, ["log", "-1", "--format=%s", "HEAD"]))?.trim();
-    const fileWord = files.length === 1 ? "file" : "files";
-    const head = label?.trim() || subject || "Working-tree change";
-    const against = fromTrunk ? "vs trunk" : "uncommitted (vs HEAD)";
-    return {
-      description: `${head} (${files.length} ${fileWord} changed ${against})`,
-      files
-    };
-  } catch {
-    return null;
+    return { body: JSON.stringify(sanitized), dropped };
   }
 }
-async function resolveBase(git, root) {
-  const forced = process.env?.BITFAB_CODE_CHANGE_BASE;
-  if (forced && await refExists(git, root, forced)) {
-    const base = (await git(root, ["merge-base", "HEAD", forced]))?.trim() || (await git(root, ["rev-parse", "--verify", forced]))?.trim() || null;
-    return base ? { base, fromTrunk: true } : null;
+var init_serializePayload = __esm({
+  "src/serializePayload.ts"() {
+    "use strict";
+    init_warnOnce();
   }
-  for (const candidate of TRUNK_CANDIDATES) {
-    if (!await refExists(git, root, candidate)) {
-      continue;
-    }
-    const mb = (await git(root, ["merge-base", "HEAD", candidate]))?.trim();
-    if (mb) {
-      return { base: mb, fromTrunk: true };
-    }
+});
+
+// src/readEnv.ts
+function readEnv(name) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[name];
   }
-  return await refExists(git, root, "HEAD") ? { base: "HEAD", fromTrunk: false } : null;
-}
-async function refExists(git, root, ref) {
-  return await git(root, ["rev-parse", "--verify", `${ref}^{object}`]) !== null;
+  return void 0;
 }
-async function readWorkingFile(readFile, root, path) {
-  try {
-    const { join } = await import("path");
-    return await readFile(join(root, path), "utf8");
-  } catch {
-    return "";
+var init_readEnv = __esm({
+  "src/readEnv.ts"() {
+    "use strict";
   }
-}
-function parseNameStatusZ(raw) {
-  const parts = raw.split(NUL).filter((p) => p.length > 0);
-  const out = [];
-  for (let i = 0; i + 1 < parts.length; i += 2) {
-    out.push({ status: parts[i].charAt(0), path: parts[i + 1] });
+});
+
+// src/unrefTimer.ts
+function unrefTimer(timer) {
+  const handle = timer;
+  if (typeof handle.unref === "function") {
+    handle.unref();
   }
-  return out;
 }
-function looksBinary(s) {
-  return s.slice(0, 8e3).includes(NUL);
-}
-var MAX_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES, TRUNK_CANDIDATES, NUL;
-var init_codeChange = __esm({
-  "src/codeChange.ts"() {
+var init_unrefTimer = __esm({
+  "src/unrefTimer.ts"() {
     "use strict";
-    MAX_FILES = 60;
-    MAX_FILE_BYTES = 5e5;
-    MAX_TOTAL_BYTES = 2e6;
-    TRUNK_CANDIDATES = [
-      "origin/HEAD",
-      "origin/main",
-      "origin/master",
-      "main",
-      "master"
-    ];
-    NUL = String.fromCharCode(0);
   }
 });
 
-// src/replay.ts
-var replay_exports = {};
-__export(replay_exports, {
-  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
-  replay: () => replay,
-  reportReplayProgress: () => reportReplayProgress
-});
-function dbBranchEnabled(dbBranch) {
-  return dbBranch !== void 0 && dbBranch !== false;
+// src/otel.ts
+function readBoundedIntEnv(name, max, fallback, warnKey) {
+  const raw = readEnv(name);
+  if (raw === void 0) {
+    return fallback;
+  }
+  const value = Number(raw);
+  if (Number.isInteger(value) && value > 0 && value <= max) {
+    return value;
+  }
+  warnOnce(
+    warnKey,
+    `${name} must be a positive integer no greater than ${max}; using ${fallback}`
+  );
+  return fallback;
 }
-function resolveDbBranchSettings(dbBranch) {
-  if (!dbBranch || dbBranch === true) {
-    return void 0;
+function logError(message, error) {
+  try {
+    if (error === void 0) {
+      console.error(`[bitfab] ${message}`);
+    } else {
+      console.error(`[bitfab] ${message}`, error);
+    }
+  } catch {
   }
-  const { minCu, maxCu, warmupSql } = dbBranch;
-  const settings = {
-    ...minCu === void 0 ? {} : { minCu },
-    ...maxCu === void 0 ? {} : { maxCu },
-    ...warmupSql === void 0 ? {} : { warmupSql }
-  };
-  return Object.keys(settings).length === 0 ? void 0 : settings;
 }
-function reportReplayProgress(progress) {
-  const stderr = typeof process !== "undefined" ? process.stderr : void 0;
-  if (!stderr) {
+function recordTraceSubmission(operation, payload) {
+  const sourceTraceId = resolveSourceTraceId(payload);
+  if (sourceTraceId === void 0) {
     return;
   }
-  try {
-    stderr.write(`${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress)}
-`);
-  } catch {
+  if (operation === "external_span") {
+    const rawSpan = asRecord(payload.rawSpan);
+    if (typeof rawSpan?.id !== "string") {
+      submissionCounter += 1;
+    }
+    const sourceSpanId = typeof rawSpan?.id === "string" ? rawSpan.id : `submission-${submissionCounter}`;
+    const existing = traceSubmissionSpanIds.get(sourceTraceId);
+    if (existing) {
+      existing.add(sourceSpanId);
+    } else {
+      traceSubmissionSpanIds.set(sourceTraceId, /* @__PURE__ */ new Set([sourceSpanId]));
+    }
+    return;
+  }
+  if (payload.completed !== true) {
+    return;
+  }
+  if (typeof payload.testRunId === "string") {
+    replayTraceSubmissions.add(sourceTraceId);
+    if (!traceSubmissionSpanIds.has(sourceTraceId)) {
+      traceSubmissionSpanIds.set(sourceTraceId, /* @__PURE__ */ new Set());
+    }
+  } else {
+    traceSubmissionSpanIds.delete(sourceTraceId);
   }
 }
-function deserializeInputs(spanData) {
-  const inputMeta = spanData.input_meta;
-  const rawInput = spanData.input;
-  if (inputMeta !== void 0 && inputMeta !== null) {
-    const deserialized = deserializeValue({ json: rawInput, meta: inputMeta });
-    if (Array.isArray(deserialized)) {
-      return deserialized;
+function takeReplaySpanCounts(traceIds) {
+  const counts = {};
+  for (const traceId of traceIds) {
+    if (!replayTraceSubmissions.has(traceId)) {
+      continue;
     }
-    return deserialized !== void 0 && deserialized !== null ? [deserialized] : [];
+    counts[traceId] = traceSubmissionSpanIds.get(traceId)?.size ?? 0;
+    traceSubmissionSpanIds.delete(traceId);
+    replayTraceSubmissions.delete(traceId);
   }
-  if (Array.isArray(rawInput)) {
-    return rawInput;
+  return counts;
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function resolveSourceTraceId(payload) {
+  if (typeof payload.sourceTraceId === "string") {
+    return payload.sourceTraceId;
   }
-  return rawInput !== void 0 && rawInput !== null ? [rawInput] : [];
+  const rawTrace = asRecord(payload.externalTrace) ?? asRecord(payload.rawTrace);
+  return typeof rawTrace?.id === "string" ? rawTrace.id : void 0;
 }
-function deserializeOutput(spanData) {
-  const outputMeta = spanData.output_meta;
-  const rawOutput = spanData.output;
-  if (outputMeta !== void 0 && outputMeta !== null) {
-    return deserializeValue({ json: rawOutput, meta: outputMeta });
+function otlpValue(value) {
+  if (typeof value === "boolean") {
+    return { boolValue: value };
   }
-  return rawOutput;
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  if (typeof value === "string") {
+    return { stringValue: value };
+  }
+  if (Array.isArray(value)) {
+    return { arrayValue: { values: value.map(otlpValue) } };
+  }
+  return { stringValue: String(value) };
 }
-function buildMockTree(rootNode) {
-  const spans = /* @__PURE__ */ new Map();
-  const counters = /* @__PURE__ */ new Map();
-  function walk(node) {
-    const key = node.traceFunctionKey;
-    if (key) {
-      const name = node.spanName || key;
-      const counterKey = `${key}:${name}`;
-      const index = counters.get(counterKey) ?? 0;
-      counters.set(counterKey, index + 1);
-      spans.set(`${counterKey}:${index}`, {
-        sourceSpanId: node.sourceSpanId,
-        externalSpanId: node.externalSpanId,
-        output: node.output,
-        outputMeta: node.outputMeta
-      });
-    }
-    for (const child of node.children) {
-      walk(child);
-    }
+function otlpAttributes(attributes) {
+  if (!attributes) {
+    return [];
   }
-  for (const child of rootNode.children) {
-    walk(child);
+  return Object.entries(attributes).filter(([, value]) => value !== void 0).map(([key, value]) => ({ key, value: otlpValue(value) }));
+}
+function hrTimeToNanoString(time) {
+  if (!time) {
+    return "0";
   }
-  return { spans };
+  return `${time[0]}${String(time[1]).padStart(9, "0")}`;
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, includeDbBranchLease, dbBranchSettings, adaptInputs) {
-  let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
-  let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
-  let dbSnapshotRef = serverItem.dbSnapshotRef;
-  let inputs = [];
-  let originalOutput;
-  let result;
-  let error = null;
-  const pendingPersistence = [];
-  const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
-  const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
-  try {
-    if (includeDbBranchLease && !lease && !leaseError) {
-      const resolved = await httpClient.resolveDbBranchLease(
-        testRunId,
-        originalTraceId,
-        dbBranchSettings
-      );
-      lease = resolved.lease ?? void 0;
-      leaseError = resolved.leaseError ?? void 0;
-      dbSnapshotRef = resolved.dbSnapshotRef ?? dbSnapshotRef;
-    }
-    if (leaseError) {
-      throw new BitfabError(
-        `Replay requested a database branch for trace ${originalTraceId} but it could not be resolved (${leaseError.code}): ${leaseError.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`
-      );
-    }
-    const span = await httpClient.getExternalSpan(originalSpanId);
-    const spanData = span.rawData?.span_data ?? {};
-    inputs = deserializeInputs(spanData);
-    originalOutput = deserializeOutput(spanData);
-    if (adaptInputs) {
-      inputs = adaptInputs(inputs, {
-        originalTraceId,
-        originalSpanId,
-        // Deprecated aliases for originalTraceId/originalSpanId.
-        sourceTraceId: originalTraceId,
-        sourceSpanId: originalSpanId
-      });
-    }
-    const hasOverrides = resolvedOverrides.length > 0;
-    const needTree = mockStrategy === "all" || mockStrategy === "marked" || hasOverrides;
-    const includeOutputs = mockStrategy === "all";
-    let mockTree;
-    if (needTree) {
-      try {
-        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 original span ${originalSpanId}.`
-          );
-        } else {
-          mockTree = void 0;
-        }
-      } catch (e) {
-        if (mockStrategy === "all" || hasOverrides) {
-          throw e;
-        }
-        mockTree = void 0;
-      }
-    }
-    const outputCache = /* @__PURE__ */ new Map();
-    const fetchSpanOutput = mockTree && !includeOutputs ? (externalSpanId) => {
-      let pending = outputCache.get(externalSpanId);
-      if (!pending) {
-        pending = httpClient.getExternalSpan(externalSpanId).then(
-          (s) => deserializeOutput(
-            s.rawData?.span_data ?? {}
-          )
-        );
-        outputCache.set(externalSpanId, pending);
-      }
-      return pending;
-    } : void 0;
-    const maybePromise = runWithReplayContext(
-      {
-        testRunId,
-        traceId: replayedTraceId,
-        inputSourceSpanId: span.id,
-        inputSourceTraceId: span.externalTraceId,
-        sourceBitfabTraceId: originalTraceId,
-        mockTree,
-        callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
-        mockStrategy,
-        mockOverrides: hasOverrides ? resolvedOverrides : void 0,
-        fetchSpanOutput,
-        dbBranchLease: lease,
-        pendingPersistence
-      },
-      () => fn(...inputs)
-    );
-    result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
-  } catch (e) {
-    error = e instanceof Error ? e.message : String(e);
-  } finally {
-    await Promise.allSettled(pendingPersistence);
-    if (lease) {
-      try {
-        await httpClient.releaseDbBranchLease(lease.neonBranchId);
-      } catch (e) {
-        try {
-          console.warn(
-            `Bitfab: failed to release DB branch ${lease.neonBranchId} (TTL janitor will catch it): ${e instanceof Error ? e.message : String(e)}`
-          );
-        } catch {
-        }
-      }
-    }
+function spanToOtlp(span) {
+  const spanContext = span.spanContext();
+  const result = {
+    traceId: spanContext.traceId,
+    spanId: spanContext.spanId,
+    name: span.name,
+    kind: span.kind + 1,
+    startTimeUnixNano: hrTimeToNanoString(span.startTime),
+    endTimeUnixNano: hrTimeToNanoString(span.endTime),
+    attributes: otlpAttributes(span.attributes),
+    droppedAttributesCount: span.droppedAttributesCount,
+    droppedEventsCount: span.droppedEventsCount,
+    droppedLinksCount: span.droppedLinksCount,
+    status: {
+      code: span.status.code,
+      ...span.status.message ? { message: span.status.message } : {}
+    },
+    flags: spanContext.traceFlags
+  };
+  const parentSpanId = span.parentSpanContext?.spanId;
+  if (parentSpanId) {
+    result.parentSpanId = parentSpanId;
+  }
+  if (spanContext.traceState) {
+    result.traceState = spanContext.traceState.serialize();
   }
+  return result;
+}
+function buildOtlpRequest(first, spans) {
+  const scope = first.instrumentationScope;
   return {
-    // 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,
-    error,
-    durationMs: serverItem.durationMs ?? null,
-    // Filled in by replay() from the complete-replay response once the
-    // replay traces are persisted and their spans aggregated server-side.
-    // Null here (and on older servers) means "replay tokens not known".
-    tokens: null,
-    model: serverItem.model ?? null,
-    dbSnapshotRef: dbSnapshotRef ?? null
+    resourceSpans: [
+      {
+        resource: {
+          attributes: otlpAttributes(
+            first.resource.attributes
+          )
+        },
+        scopeSpans: [
+          {
+            scope: { name: scope.name, version: scope.version ?? "" },
+            spans
+          }
+        ]
+      }
+    ]
   };
 }
-async function mapWithConcurrency(tasks, maxConcurrency, onSettled) {
-  const results = new Array(tasks.length);
-  let nextIndex = 0;
-  async function worker() {
-    while (nextIndex < tasks.length) {
-      const index = nextIndex++;
-      const result = await tasks[index]();
-      results[index] = result;
-      onSettled?.(result, index);
+function encodedSize(value) {
+  const json = JSON.stringify(value);
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(json).length;
+  }
+  return json.length;
+}
+function delay(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    unrefTimer(timer);
+  });
+}
+async function withDeadline(work, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      work,
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+        unrefTimer(timer);
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
     }
   }
+}
+async function mapWithConcurrency(items, limit, task) {
+  const results = new Array(items.length);
+  let next = 0;
   const workers = Array.from(
-    { length: Math.min(maxConcurrency, tasks.length) },
-    () => worker()
+    { length: Math.min(Math.max(limit, 1), items.length) },
+    async () => {
+      while (next < items.length) {
+        const index = next;
+        next += 1;
+        results[index] = await task(items[index]);
+      }
+    }
   );
   await Promise.all(workers);
   return results;
 }
-async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, registeredOverrides = []) {
-  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}).`
-      );
-    }
+function responseStatus(error) {
+  return error instanceof BitfabError ? error.status : void 0;
+}
+function isRetryable(error) {
+  const status = responseStatus(error);
+  if (status === void 0) {
+    return true;
   }
-  if (options?.limit !== void 0 && options?.traceIds !== void 0) {
-    try {
-      console.warn(
-        "Bitfab: limit is ignored when traceIds is passed: the explicit trace ID list already determines how many traces replay."
-      );
-    } catch {
+  return RETRYABLE_STATUSES.has(status) || status >= 500;
+}
+function normalizeCollectorEndpoint(endpoint) {
+  const trimmed = endpoint.replace(/\/+$/, "");
+  return trimmed.endsWith("/v1/traces") ? trimmed : `${trimmed}/v1/traces`;
+}
+function endSpan(span, endTime) {
+  span.end(endTime);
+}
+function spanName(operation, payload) {
+  if (operation === "external_span") {
+    const spanData = asRecord(asRecord(payload.rawSpan)?.span_data);
+    if (typeof spanData?.name === "string") {
+      return spanData.name;
     }
   }
-  await replayContextReady;
-  let codeChangeDescription = options?.codeChangeDescription;
-  let codeChangeFiles = options?.codeChangeFiles;
-  if (codeChangeFiles === void 0) {
-    const captured = await resolveAutoCodeChange(options?.name);
-    if (captured) {
-      codeChangeFiles = captured.files;
-      if (codeChangeDescription === void 0) {
-        codeChangeDescription = captured.description;
-      }
-    }
+  if (typeof payload.traceFunctionKey === "string") {
+    return payload.traceFunctionKey;
   }
-  const {
-    testRunId,
-    testRunUrl,
-    items: serverItems
-  } = await httpClient.startReplay(
-    traceFunctionKey,
-    // 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?.name,
-    codeChangeDescription,
-    codeChangeFiles,
-    dbBranchEnabled(options?.dbBranch),
-    // includeDbBranchLease
-    options?.experimentGroupId,
-    options?.datasetId,
-    options?.graderIds,
-    resolveDbBranchSettings(options?.dbBranch)
-  );
-  const mockStrategy = options?.mock ?? "marked";
-  const maxConcurrency = options?.maxConcurrency ?? 10;
-  const resolvedOverrides = [
-    ...normalizeMockOverrides(options?.mockOverride),
-    ...registeredOverrides
-  ];
-  const replayedTraceIds = serverItems.map(() => randomUuid());
-  const tasks = serverItems.map(
-    (serverItem, index) => () => processItem(
-      httpClient,
-      serverItem,
-      fn,
-      testRunId,
-      mockStrategy,
-      resolvedOverrides,
-      replayedTraceIds[index],
-      dbBranchEnabled(options?.dbBranch),
-      resolveDbBranchSettings(options?.dbBranch),
-      options?.adaptInputs
+  return `bitfab.${operation}`;
+}
+function payloadTimestamp(payload, field) {
+  const rawSpan = asRecord(payload.rawSpan);
+  const rawTrace = asRecord(payload.externalTrace) ?? asRecord(payload.rawTrace);
+  const raw = rawSpan?.[field] ?? rawTrace?.[field];
+  if (typeof raw !== "string") {
+    return void 0;
+  }
+  const parsed = Date.parse(raw);
+  return Number.isNaN(parsed) ? void 0 : parsed;
+}
+function hasError(payload) {
+  const spanData = asRecord(asRecord(payload.rawSpan)?.span_data);
+  if (spanData?.error != null) {
+    return true;
+  }
+  const errors = payload.errors;
+  return Array.isArray(errors) ? errors.length > 0 : Boolean(errors);
+}
+function createOtelTransport(options) {
+  return new OtelBatchTransport({
+    ...options,
+    collectorEndpoint: readEnv(COLLECTOR_ENDPOINT_ENV) || void 0,
+    exportConcurrency: readBoundedIntEnv(
+      EXPORT_CONCURRENCY_ENV,
+      MAX_EXPORT_CONCURRENCY,
+      DEFAULT_EXPORT_CONCURRENCY,
+      "otel-export-concurrency-invalid"
+    ),
+    maxRequestBytes: readBoundedIntEnv(
+      MAX_REQUEST_BYTES_ENV,
+      MAX_EXPORT_REQUEST_BYTES,
+      MAX_EXPORT_REQUEST_BYTES,
+      "otel-max-request-bytes-invalid"
     )
+  });
+}
+async function forEachLiveTransport(timeoutMs, run) {
+  const deadline = Date.now() + Math.max(timeoutMs, 0);
+  let succeeded = true;
+  for (const transport of [...liveTransports]) {
+    succeeded = await run(transport, Math.max(0, deadline - Date.now())) && succeeded;
+  }
+  return succeeded;
+}
+function flushOtelTransports(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS) {
+  return forEachLiveTransport(
+    timeoutMs,
+    (transport, remaining) => transport.flush(remaining)
   );
-  const total = tasks.length;
-  let completed = 0;
-  let succeeded = 0;
-  let errored = 0;
-  const resultItems = await mapWithConcurrency(
-    tasks,
-    maxConcurrency,
-    options?.onProgress ? (item) => {
-      completed += 1;
-      if (item.error === null) {
-        succeeded += 1;
-      } else {
-        errored += 1;
+}
+function shutdownOtelTransports(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS) {
+  return forEachLiveTransport(
+    timeoutMs,
+    (transport, remaining) => transport.shutdown(remaining)
+  );
+}
+var import_api, import_core, import_resources, import_sdk_trace_base, OPERATION_ATTRIBUTE, PAYLOAD_ATTRIBUTE, OTLP_TRACES_ENDPOINT, MAX_EXPORT_REQUEST_BYTES, MAX_REQUEST_BYTES_ENV, EXPORT_CONCURRENCY_ENV, COLLECTOR_ENDPOINT_ENV, MAX_QUEUE_SIZE, DIRECT_MAX_EXPORT_BATCH_SIZE, COLLECTOR_MAX_EXPORT_BATCH_SIZE, DIRECT_MAX_REQUEST_BATCH_SIZE, DEFAULT_EXPORT_CONCURRENCY, MAX_EXPORT_CONCURRENCY, SCHEDULE_DELAY_MILLIS, EXPORT_TIMEOUT_MILLIS, RETRY_DELAY_MILLIS, MAX_SEND_ATTEMPTS, DEFAULT_LIFECYCLE_TIMEOUT_MS, RETRYABLE_STATUSES, liveTransports, traceSubmissionSpanIds, replayTraceSubmissions, submissionCounter, OtlpPayloadTooLargeError, OtlpPartialSuccessError, BitfabSpanExporter, CollectorSpanExporter, DeliveryTrackingExporter, OtelBatchTransport;
+var init_otel = __esm({
+  "src/otel.ts"() {
+    "use strict";
+    import_api = require("@opentelemetry/api");
+    import_core = require("@opentelemetry/core");
+    import_resources = require("@opentelemetry/resources");
+    import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
+    init_constants();
+    init_errors();
+    init_readEnv();
+    init_serializePayload();
+    init_unrefTimer();
+    init_warnOnce();
+    OPERATION_ATTRIBUTE = "bitfab.operation";
+    PAYLOAD_ATTRIBUTE = "bitfab.payload";
+    OTLP_TRACES_ENDPOINT = "/api/sdk/otel/v1/traces";
+    MAX_EXPORT_REQUEST_BYTES = 3e6;
+    MAX_REQUEST_BYTES_ENV = "BITFAB_OTEL_MAX_REQUEST_BYTES";
+    EXPORT_CONCURRENCY_ENV = "BITFAB_OTEL_EXPORT_CONCURRENCY";
+    COLLECTOR_ENDPOINT_ENV = "BITFAB_OTEL_EXPORTER_ENDPOINT";
+    MAX_QUEUE_SIZE = 8192;
+    DIRECT_MAX_EXPORT_BATCH_SIZE = 512;
+    COLLECTOR_MAX_EXPORT_BATCH_SIZE = 32;
+    DIRECT_MAX_REQUEST_BATCH_SIZE = 8;
+    DEFAULT_EXPORT_CONCURRENCY = 32;
+    MAX_EXPORT_CONCURRENCY = 64;
+    SCHEDULE_DELAY_MILLIS = 5e3;
+    EXPORT_TIMEOUT_MILLIS = 3e4;
+    RETRY_DELAY_MILLIS = 100;
+    MAX_SEND_ATTEMPTS = 3;
+    DEFAULT_LIFECYCLE_TIMEOUT_MS = 3e4;
+    RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429]);
+    liveTransports = /* @__PURE__ */ new Set();
+    traceSubmissionSpanIds = /* @__PURE__ */ new Map();
+    replayTraceSubmissions = /* @__PURE__ */ new Set();
+    submissionCounter = 0;
+    OtlpPayloadTooLargeError = class extends Error {
+    };
+    OtlpPartialSuccessError = class extends Error {
+    };
+    BitfabSpanExporter = class {
+      constructor(directSender, maxRequestBytes, maxRequestBatchSize, exportConcurrency) {
+        this.directSender = directSender;
+        this.maxRequestBytes = maxRequestBytes;
+        this.maxRequestBatchSize = maxRequestBatchSize;
+        this.exportConcurrency = exportConcurrency;
       }
-      try {
-        options?.onProgress?.({
-          testRunId,
-          completed,
-          total,
-          succeeded,
-          errored,
-          item: {
-            // 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,
-            error: item.error,
-            durationMs: item.durationMs,
-            tokens: item.tokens,
-            model: item.model,
-            dbSnapshotRef: item.dbSnapshotRef
+      export(spans, resultCallback) {
+        void this.exportAsync(spans).then(
+          (succeeded) => {
+            resultCallback({
+              code: succeeded ? import_core.ExportResultCode.SUCCESS : import_core.ExportResultCode.FAILED
+            });
+          },
+          (error) => {
+            resultCallback({ code: import_core.ExportResultCode.FAILED, error });
+          }
+        );
+      }
+      async exportAsync(spans) {
+        if (spans.length === 0) {
+          return true;
+        }
+        let encoded;
+        try {
+          encoded = spans.map(spanToOtlp);
+        } catch (error) {
+          logError("failed to encode an OpenTelemetry span batch", error);
+          return false;
+        }
+        const first = spans[0];
+        const batches = this.buildRequestBatches(first, encoded);
+        const results = await mapWithConcurrency(
+          batches,
+          this.exportConcurrency,
+          (batch) => this.send(first, batch)
+        );
+        return results.every(Boolean);
+      }
+      buildRequestBatches(first, spans) {
+        const batches = [];
+        let current = [];
+        for (const span of spans) {
+          if (current.length >= this.maxRequestBatchSize) {
+            batches.push(current);
+            current = [];
+          }
+          const candidate = [...current, span];
+          if (current.length > 0 && encodedSize(buildOtlpRequest(first, candidate)) > this.maxRequestBytes) {
+            batches.push(current);
+            current = [span];
+          } else {
+            current = candidate;
+          }
+        }
+        if (current.length > 0) {
+          batches.push(current);
+        }
+        return batches;
+      }
+      async send(first, spans) {
+        const payload = buildOtlpRequest(first, spans);
+        if (encodedSize(payload) > this.maxRequestBytes) {
+          logError(
+            "a single OpenTelemetry span exceeded the configured request-size target and could not be exported"
+          );
+          return false;
+        }
+        try {
+          await this.sendWithRetries(payload);
+          return true;
+        } catch (error) {
+          if (error instanceof OtlpPayloadTooLargeError) {
+            logError(
+              spans.length === 1 ? "a single OpenTelemetry span exceeded the ingestion request limit and could not be exported" : "an OpenTelemetry span batch exceeded the ingestion request limit and could not be exported"
+            );
+            return false;
+          }
+          if (error instanceof OtlpPartialSuccessError) {
+            return false;
+          }
+          logError("failed to export an OpenTelemetry span batch", error);
+          return false;
+        }
+      }
+      /**
+       * Retries transient failures. Span and trace-completion carriers are safe to
+       * retry: the server keys them idempotently on `sourceSpanId`/`sourceTraceId`,
+       * so a duplicate delivery cannot create a duplicate row.
+       *
+       * KNOWN LIMITATION: an `internal_trace` (a `call()` BAML trace) carries no
+       * such key, so retrying a batch that holds one can create a duplicate trace -
+       * including when a request times out client-side but the server goes on to
+       * persist it. Accepted deliberately for now, matching the other SDKs, rather
+       * than skipping retries for a whole batch or inventing an idempotency scheme
+       * the server does not yet understand. The fix is a client-supplied
+       * idempotency key that ingestion dedupes on.
+       */
+      async sendWithRetries(payload) {
+        for (let attempt = 0; attempt < MAX_SEND_ATTEMPTS; attempt += 1) {
+          try {
+            const response = await this.directSender(
+              OTLP_TRACES_ENDPOINT,
+              payload,
+              EXPORT_TIMEOUT_MILLIS
+            );
+            const partialSuccess = asRecord(response?.partialSuccess);
+            const rejected = partialSuccess?.rejectedSpans;
+            if (rejected !== void 0 && rejected !== "0" && rejected !== 0) {
+              logError(
+                `OTLP ingestion rejected ${rejected} span(s): ${partialSuccess?.errorMessage ?? "no reason provided"}`
+              );
+              throw new OtlpPartialSuccessError();
+            }
+            return;
+          } catch (error) {
+            if (error instanceof OtlpPartialSuccessError) {
+              throw error;
+            }
+            if (responseStatus(error) === 413) {
+              throw new OtlpPayloadTooLargeError();
+            }
+            if (attempt === MAX_SEND_ATTEMPTS - 1 || !isRetryable(error)) {
+              throw error;
+            }
+            await delay(RETRY_DELAY_MILLIS);
+          }
+        }
+      }
+      async shutdown() {
+      }
+      async forceFlush() {
+      }
+    };
+    CollectorSpanExporter = class {
+      constructor(endpoint, apiKey, maxRequestBytes) {
+        this.endpoint = endpoint;
+        this.apiKey = apiKey;
+        this.maxRequestBytes = maxRequestBytes;
+      }
+      /**
+       * Loaded through a dynamic import rather than a top-level one so bundlers
+       * code-split it: Collector delivery is opt-in, and a consumer who never sets
+       * an endpoint should not pay for the exporter in their initial bundle. It is
+       * a hard dependency, so this cannot fail for want of the package.
+       */
+      loadExporterModule() {
+        if (!this.pendingModule) {
+          this.pendingModule = import("@opentelemetry/exporter-trace-otlp-proto");
+        }
+        return this.pendingModule;
+      }
+      export(spans, resultCallback) {
+        void this.exportAsync(spans).then(
+          (succeeded) => {
+            resultCallback({
+              code: succeeded ? import_core.ExportResultCode.SUCCESS : import_core.ExportResultCode.FAILED
+            });
+          },
+          (error) => {
+            resultCallback({ code: import_core.ExportResultCode.FAILED, error });
+          }
+        );
+      }
+      async exportAsync(spans) {
+        if (spans.length === 0) {
+          return true;
+        }
+        let delegate;
+        try {
+          delegate = await this.resolveDelegate();
+        } catch (error) {
+          logError("failed to build the OTLP Collector exporter", error);
+          return false;
+        }
+        const results = await Promise.all(
+          this.partition(spans).map(
+            (batch) => new Promise((resolve) => {
+              try {
+                delegate.export(batch, (result) => {
+                  resolve(result.code === import_core.ExportResultCode.SUCCESS);
+                });
+              } catch (error) {
+                logError("Collector export threw", error);
+                resolve(false);
+              }
+            })
+          )
+        );
+        return results.every(Boolean);
+      }
+      /**
+       * Partition by the encoded JSON size of each carrier rather than its encoded
+       * protobuf size. Protobuf is strictly smaller than the equivalent JSON for
+       * these payloads, so the JSON figure is a conservative bound that keeps every
+       * request under the target without pulling `@opentelemetry/otlp-transformer`
+       * into the dependency set purely to measure bytes.
+       */
+      partition(spans) {
+        const batches = [];
+        let current = [];
+        let currentSize = 0;
+        for (const span of spans) {
+          const size = encodedSize(spanToOtlp(span));
+          if (current.length > 0 && currentSize + size > this.maxRequestBytes) {
+            batches.push(current);
+            current = [];
+            currentSize = 0;
           }
+          current.push(span);
+          currentSize += size;
+        }
+        if (current.length > 0) {
+          batches.push(current);
+        }
+        return batches;
+      }
+      async resolveDelegate() {
+        const apiKey = this.apiKey() ?? "";
+        if (this.delegate && this.delegateApiKey === apiKey) {
+          return this.delegate;
+        }
+        const { OTLPTraceExporter } = await this.loadExporterModule();
+        const previous = this.delegate;
+        this.delegate = new OTLPTraceExporter({
+          url: this.endpoint,
+          headers: { Authorization: `Bearer ${apiKey}` },
+          timeoutMillis: EXPORT_TIMEOUT_MILLIS
         });
-      } catch {
+        this.delegateApiKey = apiKey;
+        if (previous) {
+          void previous.shutdown().catch(() => {
+          });
+        }
+        return this.delegate;
       }
-    } : void 0
-  );
-  const completeResult = await httpClient.completeReplay(testRunId);
-  const serverTraceIds = completeResult.traceIds;
-  const replayTokens = completeResult.tokens;
-  if (serverTraceIds !== void 0) {
-    const missing = [];
-    let completedCount = 0;
-    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);
+      async shutdown() {
+        await this.delegate?.shutdown();
+      }
+      async forceFlush() {
+        await this.delegate?.forceFlush?.();
+      }
+    };
+    DeliveryTrackingExporter = class {
+      constructor(exporter) {
+        this.exporter = exporter;
+        // Deliberately unscoped, matching the Python SDK. An export can outlive
+        // OTel's export timeout and report failure after the flush that was waiting
+        // on it already returned, so that failure surfaces on the NEXT flush instead.
+        // That over-reports: a good flush can inherit an older failure. The
+        // alternative - discarding failures from completed flush windows - under-
+        // reports, and `BatchSpanProcessor` also runs scheduled exports that belong
+        // to no flush at all, so their failures would vanish entirely. For a
+        // telemetry SDK a false "flush failed" is investigable; a false "flush
+        // succeeded" silently loses traces. We take the noisy direction on purpose.
+        this.failedExports = 0;
+      }
+      export(spans, resultCallback) {
+        try {
+          this.exporter.export(spans, (result) => {
+            if (result.code !== import_core.ExportResultCode.SUCCESS) {
+              this.failedExports += 1;
+            }
+            resultCallback(result);
+          });
+        } catch (error) {
+          this.failedExports += 1;
+          resultCallback({ code: import_core.ExportResultCode.FAILED, error });
         }
       }
-      if (mapped !== void 0) {
-        item.tokens = replayTokens?.[mapped] ?? null;
+      takeFailedExports() {
+        const failed = this.failedExports;
+        this.failedExports = 0;
+        return failed;
       }
-    }
-    if (completedCount > 0 && missing.length === completedCount) {
-      const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
-      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}). Their replay token usage is unavailable and they cannot be labeled.`
+      shutdown() {
+        return this.exporter.shutdown();
+      }
+      forceFlush() {
+        return this.exporter.forceFlush?.() ?? Promise.resolve();
+      }
+    };
+    OtelBatchTransport = class {
+      constructor(options) {
+        this.closed = false;
+        const collectorEndpoint = options.collectorEndpoint;
+        const maxRequestBytes = options.maxRequestBytes ?? MAX_EXPORT_REQUEST_BYTES;
+        const maxRequestBatchSize = options.maxRequestBatchSize ?? DIRECT_MAX_REQUEST_BATCH_SIZE;
+        if (maxRequestBatchSize <= 0) {
+          throw new BitfabError("maxRequestBatchSize must be a positive integer");
+        }
+        this.deliveryTracker = new DeliveryTrackingExporter(
+          collectorEndpoint === void 0 ? new BitfabSpanExporter(
+            options.directSender,
+            maxRequestBytes,
+            maxRequestBatchSize,
+            options.exportConcurrency ?? DEFAULT_EXPORT_CONCURRENCY
+          ) : new CollectorSpanExporter(
+            normalizeCollectorEndpoint(collectorEndpoint),
+            options.apiKey,
+            maxRequestBytes
+          )
         );
-      } catch {
+        this.processor = new import_sdk_trace_base.BatchSpanProcessor(this.deliveryTracker, {
+          maxQueueSize: options.maxQueueSize ?? MAX_QUEUE_SIZE,
+          maxExportBatchSize: options.maxExportBatchSize ?? (collectorEndpoint === void 0 ? DIRECT_MAX_EXPORT_BATCH_SIZE : COLLECTOR_MAX_EXPORT_BATCH_SIZE),
+          scheduledDelayMillis: SCHEDULE_DELAY_MILLIS,
+          exportTimeoutMillis: options.exportTimeoutMillis ?? EXPORT_TIMEOUT_MILLIS
+        });
+        this.provider = new import_sdk_trace_base.BasicTracerProvider({
+          sampler: new import_sdk_trace_base.AlwaysOnSampler(),
+          resource: (0, import_resources.resourceFromAttributes)({
+            "service.name": "bitfab-typescript-sdk",
+            "service.version": __version__
+          }),
+          spanLimits: {
+            attributeCountLimit: 2,
+            attributeValueLengthLimit: Number.POSITIVE_INFINITY
+          },
+          spanProcessors: [this.processor]
+        });
+        this.tracer = this.provider.getTracer("bitfab", __version__);
+        liveTransports.add(this);
       }
-    }
+      submit(operation, payload) {
+        recordTraceSubmission(operation, payload);
+        if (this.closed) {
+          warnOnce(
+            "otel-submit-after-shutdown",
+            "OpenTelemetry transport is shut down; dropping spans"
+          );
+          return;
+        }
+        try {
+          const { body, dropped } = serializePayloadBody(payload);
+          if (dropped.length > 0) {
+            warnOnce(
+              "otel-carrier-payload-stubbed",
+              `a span payload held non-serializable value(s) (${[
+                ...new Set(dropped)
+              ].join(", ")}); they were stubbed so the span still ships, but the trace may be incomplete or not replayable.`
+            );
+          }
+          const span = this.tracer.startSpan(spanName(operation, payload), {
+            attributes: {
+              [OPERATION_ATTRIBUTE]: operation,
+              [PAYLOAD_ATTRIBUTE]: body
+            },
+            startTime: payloadTimestamp(payload, "started_at")
+          });
+          if (hasError(payload)) {
+            span.setStatus({ code: import_api.SpanStatusCode.ERROR });
+          }
+          endSpan(span, payloadTimestamp(payload, "ended_at"));
+        } catch (error) {
+          logError("failed to queue an OpenTelemetry span", error);
+        }
+      }
+      async flush(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS) {
+        const pending = (this.pendingFlush ?? Promise.resolve(true)).then(
+          () => this.forceFlushOnce()
+        );
+        this.pendingFlush = pending.catch(() => false);
+        return withDeadline(pending, timeoutMs);
+      }
+      async forceFlushOnce() {
+        try {
+          await this.processor.forceFlush();
+        } catch (error) {
+          logError("failed to flush OpenTelemetry spans", error);
+          this.deliveryTracker.takeFailedExports();
+          return false;
+        }
+        return this.deliveryTracker.takeFailedExports() === 0;
+      }
+      async shutdown(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS) {
+        const deadline = Date.now() + Math.max(timeoutMs, 0);
+        this.closed = true;
+        const flushed = await this.flush(Math.max(0, deadline - Date.now()));
+        liveTransports.delete(this);
+        const shutdownCompleted = await withDeadline(
+          this.provider.shutdown().then(() => true).catch((error) => {
+            logError("failed to shut down the OpenTelemetry transport", error);
+            return false;
+          }),
+          Math.max(0, deadline - Date.now())
+        );
+        return flushed && shutdownCompleted;
+      }
+    };
   }
-  const result = {
-    items: resultItems,
-    testRunId,
-    testRunUrl: `${serviceUrl}${testRunUrl}`
-  };
-  await writeReplayResultFile(result);
-  try {
-    options?.onProgress?.({
-      type: "complete",
-      testRunId,
-      completed: total,
-      total,
-      succeeded,
-      errored,
-      result
-    });
-  } catch {
+});
+
+// src/transport.ts
+function createTraceTransport(options) {
+  return createOtelTransport(options);
+}
+function flushTraceTransports(timeoutMs) {
+  return flushOtelTransports(timeoutMs);
+}
+function shutdownTraceTransports(timeoutMs) {
+  return shutdownOtelTransports(timeoutMs);
+}
+function takeReplaySpanCounts2(traceIds) {
+  return takeReplaySpanCounts(traceIds);
+}
+var init_transport = __esm({
+  "src/transport.ts"() {
+    "use strict";
+    init_otel();
   }
-  return result;
+});
+
+// src/http.ts
+function awaitOnExit(promise) {
+  pendingTracePromises.add(promise);
+  void promise.finally(() => {
+    pendingTracePromises.delete(promise);
+  }).catch(() => {
+  });
+  return promise;
 }
-async function writeReplayResultFile(result) {
-  const resultPath = typeof process !== "undefined" ? process.env?.BITFAB_REPLAY_RESULT_PATH : void 0;
-  if (!resultPath) {
-    return;
+async function flushTraces(timeoutMs = 5e3) {
+  const deadline = Date.now() + Math.max(timeoutMs, 0);
+  const requestsFlushed = await awaitPendingRequests(timeoutMs);
+  const transportsFlushed = await flushTraceTransports(
+    Math.max(0, deadline - Date.now())
+  );
+  return requestsFlushed && transportsFlushed;
+}
+async function awaitPendingRequests(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
+  await replayContextReady.catch(() => {
+  });
+  return waitForPromises(Array.from(pendingTracePromises), timeoutMs);
+}
+async function waitForPromises(promises, timeoutMs) {
+  if (promises.length === 0) {
+    return true;
   }
+  let timer;
   try {
-    const [{ dirname }, { mkdir, writeFile }] = await Promise.all([
-      import("path"),
-      import("fs/promises")
+    return await Promise.race([
+      Promise.allSettled(promises).then(() => true),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+        unrefTimer(timer);
+      })
     ]);
-    await mkdir(dirname(resultPath), { recursive: true });
-    await writeFile(resultPath, `${JSON.stringify(result, null, 2)}
-`);
-  } catch (err) {
-    try {
-      console.warn(
-        `Bitfab: failed to write replay result to BITFAB_REPLAY_RESULT_PATH (${resultPath}): ${err instanceof Error ? err.message : String(err)}`
-      );
-    } catch {
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
     }
   }
 }
-var BITFAB_PROGRESS_PREFIX;
-var init_replay = __esm({
-  "src/replay.ts"() {
+var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS, EXIT_FLUSH_TIMEOUT_MS, DEFAULT_LIFECYCLE_TIMEOUT_MS2, pendingTracePromises, HttpClient;
+var init_http = __esm({
+  "src/http.ts"() {
     "use strict";
-    init_codeChange();
+    init_constants();
     init_errors();
-    init_mockOverride();
-    init_randomUuid();
     init_replayContext();
-    init_serialize();
-    BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
-  }
-});
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
-  Bitfab: () => Bitfab,
-  BitfabClaudeAgentHandler: () => BitfabClaudeAgentHandler,
-  BitfabError: () => BitfabError,
-  BitfabFunction: () => BitfabFunction,
-  BitfabLangChainCallbackHandler: () => BitfabLangGraphCallbackHandler,
-  BitfabLangGraphCallbackHandler: () => BitfabLangGraphCallbackHandler,
-  BitfabOpenAIAgentHandler: () => BitfabOpenAIAgentHandler,
-  BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
-  BitfabVercelAiHandler: () => BitfabVercelAiHandler,
-  DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
-  SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
-  __version__: () => __version__,
-  finalizers: () => finalizers,
-  flushTraces: () => flushTraces,
-  getCurrentReplayBranch: () => getCurrentReplayBranch,
-  getCurrentSpan: () => getCurrentSpan,
-  getCurrentTrace: () => getCurrentTrace,
-  reportReplayProgress: () => reportReplayProgress
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/version.generated.ts
-var __version__ = "0.33.6";
-
-// src/constants.ts
-var DEFAULT_SERVICE_URL = "https://bitfab.ai";
-
-// src/http.ts
-init_errors();
-
-// src/unrefTimer.ts
-function unrefTimer(timer) {
-  const handle = timer;
-  if (typeof handle.unref === "function") {
-    handle.unref();
-  }
-}
-
-// src/http.ts
-init_warnOnce();
-var REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS = 3e5;
-function serializePayloadBody(payload) {
-  try {
-    return { body: JSON.stringify(payload), dropped: [] };
-  } catch {
-    const dropped = [];
-    const sanitize = (value, seen) => {
-      const t = typeof value;
-      if (value === null || t === "string" || t === "number" || t === "boolean") {
-        return value;
+    init_serializePayload();
+    init_transport();
+    init_unrefTimer();
+    init_warnOnce();
+    REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS = 3e5;
+    EXIT_FLUSH_TIMEOUT_MS = 5e3;
+    DEFAULT_LIFECYCLE_TIMEOUT_MS2 = 3e4;
+    pendingTracePromises = /* @__PURE__ */ new Set();
+    if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
+      let isFlushing = false;
+      process.on("beforeExit", () => {
+        if (isFlushing) {
+          return;
+        }
+        isFlushing = true;
+        void Promise.allSettled([
+          ...Array.from(pendingTracePromises).map((p) => p.catch(() => {
+          })),
+          shutdownTraceTransports(EXIT_FLUSH_TIMEOUT_MS).catch(() => false)
+        ]).then(() => {
+          isFlushing = false;
+        });
+      });
+    }
+    HttpClient = class {
+      constructor(config) {
+        // Deferred span work owned by THIS client. The module-global set backs the
+        // process-wide `flushTraces()` and the exit hook, but per-client lifecycle
+        // must not wait on another client's slow finalize: a false `close()` failure
+        // caused by unrelated work is worse than no signal at all.
+        this.deferredWork = /* @__PURE__ */ new Set();
+        this.closed = false;
+        this.apiKey = config.apiKey;
+        this.serviceUrl = config.serviceUrl;
+        this.timeout = config.timeout ?? 12e4;
       }
-      if (t === "bigint") {
-        dropped.push("BigInt");
-        return "<unserializable: BigInt>";
+      /**
+       * Resolve the API key at the moment it is needed (request time), invoking
+       * the function form if one was supplied. Never read at construction.
+       */
+      resolveApiKey() {
+        return typeof this.apiKey === "function" ? this.apiKey() : this.apiKey;
       }
-      if (t === "function") {
-        const name = value.name || "Function";
-        dropped.push(name);
-        return `<unserializable: ${name}>`;
+      /**
+       * This client's span transport, built on first use.
+       *
+       * Lazy on purpose: a client that never sends a span must never start a batch
+       * worker. Every framework integration created from a `Bitfab` client shares
+       * the owning client's `HttpClient`, so handlers reuse this one worker instead
+       * of each spinning up their own.
+       */
+      getTraceTransport() {
+        if (this.closed) {
+          warnOnce(
+            "http-client-closed",
+            "the Bitfab client is closed; dropping spans"
+          );
+          return void 0;
+        }
+        if (!this.traceTransport) {
+          this.traceTransport = createTraceTransport({
+            apiKey: () => this.resolveApiKey(),
+            directSender: (endpoint, payload, timeoutMs) => this.request(endpoint, payload, {
+              timeout: timeoutMs
+            })
+          });
+        }
+        return this.traceTransport;
       }
-      if (t === "symbol") {
-        dropped.push("Symbol");
-        return "<unserializable: Symbol>";
+      /**
+       * Track deferred span work so this client's own lifecycle waits for it, and
+       * so the process-wide flush and exit hook do too.
+       */
+      trackDeferred(promise) {
+        this.deferredWork.add(promise);
+        void promise.finally(() => this.deferredWork.delete(promise)).catch(() => {
+        });
+        return awaitOnExit(promise);
       }
-      if (t !== "object") {
-        return void 0;
+      /**
+       * Settle only THIS client's deferred span work. Scoped deliberately: the
+       * global set can contain another client's long-running finalize, and
+       * attributing its timeout here would fail a client whose own work succeeded.
+       */
+      async settleDeferredWork(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
+        await replayContextReady.catch(() => {
+        });
+        return waitForPromises(Array.from(this.deferredWork), timeoutMs);
       }
-      const obj = value;
-      const className = obj.constructor?.name || "object";
-      if (seen.has(obj)) {
-        dropped.push(className);
-        return `<cycle: ${className}>`;
+      /**
+       * Wait for spans queued by this client to be delivered, within one deadline.
+       * Returns false on delivery failure or timeout.
+       */
+      async waitForPendingRequests(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
+        const deadline = Date.now() + Math.max(timeoutMs, 0);
+        const settled = await this.settleDeferredWork(timeoutMs);
+        const flushed = await this.traceTransport?.flush(Math.max(0, deadline - Date.now())) ?? true;
+        return settled && flushed;
       }
-      seen.add(obj);
-      let result;
-      if (Array.isArray(obj)) {
-        result = obj.map((item) => sanitize(item, seen));
-      } else if (typeof obj.toJSON === "function") {
+      /**
+       * Flush and permanently close this client's tracing transport. Idempotent:
+       * a second call joins the first rather than tearing down a pipeline the
+       * first call already owns.
+       */
+      close(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS2) {
+        if (this.closing) {
+          return this.closing;
+        }
+        const deadline = Date.now() + Math.max(timeoutMs, 0);
+        this.closing = (async () => {
+          const settled = await this.settleDeferredWork(
+            Math.max(0, deadline - Date.now())
+          );
+          this.closed = true;
+          const transport = this.traceTransport;
+          this.traceTransport = void 0;
+          const shutdownOk = await transport?.shutdown(Math.max(0, deadline - Date.now())) ?? true;
+          return settled && shutdownOk;
+        })();
+        return this.closing;
+      }
+      /**
+       * 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);
+        const { body, dropped } = serializePayloadBody(payload);
+        if (dropped.length > 0) {
+          try {
+            console.warn(
+              `Bitfab: request body to ${endpoint} held ${dropped.length} non-serializable value(s) (${[...new Set(dropped)].join(", ")}); they were stubbed so the span still sends, but the trace may be incomplete or not replayable. Capture a JSON-safe projection of this input to make it replayable.`
+            );
+          } catch {
+          }
+        }
         try {
-          result = sanitize(obj.toJSON(), seen);
-        } catch {
-          dropped.push(className);
-          result = `<unserializable: ${className}>`;
+          const response = await fetch(url, {
+            method,
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this.resolveApiKey() ?? ""}`
+            },
+            body,
+            signal: controller.signal
+          });
+          if (!response.ok) {
+            const errorText = await response.text();
+            throw new BitfabError(
+              `HTTP ${response.status}: ${errorText.slice(0, 500)}`,
+              void 0,
+              response.status
+            );
+          }
+          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);
         }
-      } else {
+      }
+      /**
+       * Look up a function by name.
+       * Blocks until complete - needed for function execution.
+       */
+      async lookupFunction(name) {
+        return this.request("/api/sdk/functions/lookup", { name });
+      }
+      async getTraceSpan(traceId, lookup) {
+        const searchParams = new URLSearchParams();
+        if (lookup.id !== void 0) {
+          searchParams.set("id", lookup.id);
+        } else {
+          searchParams.set("name", lookup.name);
+          searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
+        }
+        const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
+        const response = await this.get(endpoint);
+        return response.span;
+      }
+      async get(endpoint) {
+        const url = `${this.serviceUrl}${endpoint}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+          const response = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+            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 ${this.timeout}ms`);
+            }
+            throw new BitfabError(error.message);
+          }
+          throw new BitfabError("Unknown error occurred");
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      }
+      /**
+       * Queue an internal trace (from local BAML execution via `call()`) onto this
+       * client's batching transport. `functionId` moves into the payload because
+       * the OTLP carrier has no path to carry it.
+       */
+      sendInternalTrace(functionId, payload) {
+        this.getTraceTransport()?.submit("internal_trace", {
+          ...payload,
+          functionId,
+          sdkVersion: __version__
+        });
+      }
+      /**
+       * Queue an external span (from withSpan wrapper or OpenAI tracing) onto this
+       * client's batching transport. Fire-and-forget: the transport owns delivery,
+       * so callers await `flushTraces()` or `close()` rather than a per-span
+       * promise.
+       */
+      sendExternalSpan(payload) {
+        this.getTraceTransport()?.submit("external_span", {
+          ...payload,
+          sdkVersion: __version__
+        });
+      }
+      /**
+       * Queue an external trace completion (from OpenAI tracing) onto this
+       * client's batching transport. Fire-and-forget for the same reason as
+       * {@link HttpClient.sendExternalSpan}; replay confirms persistence with the
+       * server-authoritative barrier in `replay.ts`, not by awaiting this call.
+       */
+      sendExternalTrace(payload) {
+        this.getTraceTransport()?.submit("external_trace", {
+          ...payload,
+          sdkVersion: __version__
+        });
+      }
+      /**
+       * Partial update of an existing trace identified by its Bitfab trace ID.
+       * Used by the detached `client.getTrace(id)` handle.
+       *
+       * Blocking, like the other trace-API calls: it resolves once the server has
+       * applied the change and rejects if the server refused it. A patch targets a
+       * trace that is already closed, so there is no batch for it to ride along
+       * with and no later signal that would reveal a silent failure.
+       */
+      async patchTrace(traceId, payload) {
+        const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}`;
+        await this.request(endpoint, payload, { method: "PATCH" });
+      }
+      /**
+       * Start a replay session by fetching historical traces.
+       * Blocking call - creates a test run and returns lightweight item references.
+       */
+      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings) {
+        const payload = { traceFunctionKey };
+        if (limit !== void 0) {
+          payload.limit = limit;
+        }
+        if (traceIds) {
+          payload.traceIds = traceIds;
+        }
+        if (name !== void 0) {
+          payload.name = name;
+        }
+        if (codeChangeDescription !== void 0) {
+          payload.codeChangeDescription = codeChangeDescription;
+        }
+        if (codeChangeFiles !== void 0) {
+          payload.codeChangeFiles = codeChangeFiles;
+        }
+        if (includeDbBranchLease) {
+          payload.includeDbBranchLease = true;
+          payload.lazyDbBranchLease = true;
+        }
+        if (experimentGroupId !== void 0) {
+          payload.experimentGroupId = experimentGroupId;
+        }
+        if (datasetId !== void 0) {
+          payload.datasetId = datasetId;
+        }
+        if (graderIds !== void 0) {
+          payload.graderIds = graderIds;
+        }
+        if (dbBranchSettings !== void 0) {
+          payload.dbBranchSettings = dbBranchSettings;
+        }
+        const timeout = includeDbBranchLease ? REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS : 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.resolveApiKey() ?? ""}` },
+            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.
+       *
+       * Pass `includeOutputs: false` for a payload-free tree (structure +
+       * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
+       * span instead of all up front. Omit it (default eager) for `mock: "all"`.
+       */
+      async getSpanTree(externalSpanId, options) {
+        const query = options?.includeOutputs === false ? "?includeOutputs=false" : "";
+        const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}${query}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 3e4);
+        try {
+          const response = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+            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);
+        }
+      }
+      /**
+       * Read which of a replay run's traces the server has fully persisted.
+       *
+       * With `expectedSpanCounts`, a trace appears in the response only once it
+       * 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) {
+        return this.request(
+          "/api/sdk/replay/status",
+          { testRunId, expectedSpanCounts },
+          { timeout: 3e4 }
+        );
+      }
+      /**
+       * 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, dbBranchSettings) {
+        return this.request(
+          "/api/sdk/replay/resolveDbBranchLease",
+          { testRunId, traceId, dbBranchSettings },
+          { timeout: REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS }
+        );
+      }
+      /** 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/serialize.ts
+function describeValue(value) {
+  try {
+    const ctorName = value?.constructor?.name;
+    if (ctorName && ctorName !== "Object") {
+      return ctorName;
+    }
+  } catch {
+  }
+  return typeof value;
+}
+function unserializableStub(value, reason) {
+  warnOnce(
+    `serialize:${reason.replace(/\d+/g, "N")}`,
+    `a value could not be fully serialized for a span (${reason}); it was replaced with a placeholder. The span still ships, but its captured input/output is incomplete.`
+  );
+  let summary;
+  try {
+    summary = `<unserializable: ${describeValue(value)} (${reason})>`;
+  } catch {
+    summary = `<unserializable (${reason})>`;
+  }
+  return { json: summary };
+}
+function serializeValue(value) {
+  try {
+    const { json, meta } = import_superjson.default.serialize(value);
+    let size;
+    try {
+      size = JSON.stringify(json).length;
+    } catch {
+      return unserializableStub(value, "stringify_failed_after_superjson");
+    }
+    if (size > MAX_SERIALIZED_BYTES) {
+      return unserializableStub(value, `too_large_${size}_bytes`);
+    }
+    return meta ? { json, meta } : { json };
+  } catch {
+    try {
+      return { json: JSON.parse(JSON.stringify(value)) };
+    } catch {
+      return unserializableStub(value, "json_stringify_failed");
+    }
+  }
+}
+function deserializeValue(serialized) {
+  if (serialized.meta === void 0) {
+    return serialized.json;
+  }
+  return import_superjson.default.deserialize({
+    json: serialized.json,
+    meta: serialized.meta
+  });
+}
+function toJsonSafe(value) {
+  return toJsonSafeReport(value).safe;
+}
+function toJsonSafeReport(value) {
+  const dropped = [];
+  const safe = toJsonSafeInner(value, 0, /* @__PURE__ */ new WeakSet(), dropped);
+  try {
+    const size = JSON.stringify(safe)?.length ?? 0;
+    if (size > MAX_FRAMEWORK_SERIALIZED_BYTES) {
+      warnOnce(
+        "toJsonSafe:too_large",
+        `a framework payload exceeded ${MAX_FRAMEWORK_SERIALIZED_BYTES} bytes and was replaced with a placeholder so the span still ships. The captured state for this span is incomplete.`
+      );
+      return {
+        safe: `<unserializable: too_large_${size}_bytes>`,
+        dropped: [...dropped, `too_large_${size}_bytes`]
+      };
+    }
+  } catch {
+  }
+  return { safe, dropped };
+}
+function toJsonSafeInner(value, depth, seen, dropped) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  const className = value?.constructor?.name ?? typeof value;
+  if (depth > MAX_SAFE_DEPTH) {
+    dropped.push(className);
+    return `<${className}>`;
+  }
+  if (typeof value !== "object") {
+    if (typeof value === "function" || typeof value === "symbol") {
+      dropped.push(className);
+    }
+    try {
+      return String(value);
+    } catch {
+      dropped.push(className);
+      return `<${className}>`;
+    }
+  }
+  if (seen.has(value)) {
+    dropped.push(className);
+    return `<cycle ${className}>`;
+  }
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    result = value.map(
+      (item) => toJsonSafeInner(item, depth + 1, seen, dropped)
+    );
+  } else if (typeof value.toJSON === "function") {
+    try {
+      result = toJsonSafeInner(
+        value.toJSON(),
+        depth + 1,
+        seen,
+        dropped
+      );
+    } catch {
+      dropped.push(className);
+      result = `<${className}>`;
+    }
+  } else {
+    try {
+      const obj = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (!k.startsWith("_")) {
+          obj[k] = toJsonSafeInner(v, depth + 1, seen, dropped);
+        }
+      }
+      result = obj;
+    } catch {
+      dropped.push(className);
+      result = `<${className}>`;
+    }
+  }
+  seen.delete(value);
+  return result;
+}
+var import_superjson, MAX_SERIALIZED_BYTES, MAX_FRAMEWORK_SERIALIZED_BYTES, MAX_SAFE_DEPTH;
+var init_serialize = __esm({
+  "src/serialize.ts"() {
+    "use strict";
+    import_superjson = __toESM(require("superjson"), 1);
+    init_warnOnce();
+    MAX_SERIALIZED_BYTES = 512e3;
+    MAX_FRAMEWORK_SERIALIZED_BYTES = 2e6;
+    MAX_SAFE_DEPTH = 6;
+  }
+});
+
+// src/randomUuid.ts
+function randomUuid() {
+  const globalCrypto = globalThis.crypto;
+  if (typeof globalCrypto?.randomUUID === "function") {
+    try {
+      return globalCrypto.randomUUID();
+    } catch {
+    }
+  }
+  warnOnce(
+    "crypto-unavailable",
+    "global crypto.randomUUID is unavailable; using a non-cryptographic fallback for trace/span ids. Tracing works normally (ids are correlation-only, not security-sensitive)."
+  );
+  return fallbackUuidV4();
+}
+function fallbackUuidV4() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const rand = Math.random() * 16 | 0;
+    const value = char === "x" ? rand : rand & 3 | 8;
+    return value.toString(16);
+  });
+}
+var init_randomUuid = __esm({
+  "src/randomUuid.ts"() {
+    "use strict";
+    init_warnOnce();
+  }
+});
+
+// src/mockOverride.ts
+function resolveMockValue(value, ctx) {
+  return typeof value === "function" ? value(ctx) : value;
+}
+function normalizeMockOverrides(mockOverride) {
+  if (mockOverride === void 0) {
+    return [];
+  }
+  return Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+}
+var init_mockOverride = __esm({
+  "src/mockOverride.ts"() {
+    "use strict";
+  }
+});
+
+// src/codeChange.ts
+async function resolveAutoCodeChange(label) {
+  if (typeof process === "undefined") {
+    return null;
+  }
+  if (process.env?.BITFAB_DISABLE_CODE_CHANGE_CAPTURE) {
+    return null;
+  }
+  const fromEnv = await readCodeChangeFile();
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return captureCodeChangeFromGit(process.cwd?.() ?? ".", label);
+}
+async function readCodeChangeFile() {
+  const path = process.env?.BITFAB_CODE_CHANGE_PATH;
+  if (!path) {
+    return null;
+  }
+  try {
+    const { readFile } = await import("fs/promises");
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const files = Array.isArray(parsed?.files) && parsed.files.every(
+      (f) => typeof f === "object" && f !== null && !Array.isArray(f)
+    ) ? parsed.files : void 0;
+    const description = typeof parsed?.description === "string" ? parsed.description : void 0;
+    if (!files && description === void 0) {
+      return null;
+    }
+    return { description, files };
+  } catch {
+    return null;
+  }
+}
+async function captureCodeChangeFromGit(cwd, label) {
+  let execFile;
+  let readFile;
+  try {
+    ;
+    ({ execFile } = await import("child_process"));
+    ({ readFile } = await import("fs/promises"));
+  } catch {
+    return null;
+  }
+  const git = (dir, args) => new Promise((resolve) => {
+    execFile(
+      "git",
+      args,
+      // 30s timeout so a hung git (e.g. a network-touching ref op) can't
+      // block the whole replay indefinitely.
+      { cwd: dir, maxBuffer: 64 * 1024 * 1024, timeout: 3e4 },
+      (err, stdout) => resolve(err ? null : stdout)
+    );
+  });
+  try {
+    const root = (await git(cwd, ["rev-parse", "--show-toplevel"]))?.trim();
+    if (!root) {
+      return null;
+    }
+    const resolved = await resolveBase(git, root);
+    if (!resolved) {
+      return null;
+    }
+    const { base, fromTrunk } = resolved;
+    const blobBytes = async (ref, path) => {
+      const out = await git(root, ["cat-file", "-s", `${ref}:${path}`]);
+      const n = out ? Number.parseInt(out.trim(), 10) : Number.NaN;
+      return Number.isFinite(n) ? n : 0;
+    };
+    const workingBytes = async (path) => {
+      try {
+        const { stat } = await import("fs/promises");
+        const { join } = await import("path");
+        return (await stat(join(root, path))).size;
+      } catch {
+        return 0;
+      }
+    };
+    const tracked = await git(root, [
+      "diff",
+      "--name-status",
+      "--no-renames",
+      "-z",
+      base,
+      "--",
+      ":!.bitfab"
+    ]);
+    const untracked = await git(root, [
+      "ls-files",
+      "--others",
+      "--exclude-standard",
+      "-z",
+      "--",
+      ":!.bitfab"
+    ]);
+    const entries = [
+      ...parseNameStatusZ(tracked ?? ""),
+      ...(untracked ?? "").split(NUL).filter((p) => p.length > 0).map((path) => ({ status: "A", path }))
+    ];
+    if (entries.length === 0) {
+      return null;
+    }
+    const files = [];
+    let totalBytes = 0;
+    for (const { status, path } of entries) {
+      if (files.length >= MAX_FILES) {
+        break;
+      }
+      const beforeBytes = status === "A" ? 0 : await blobBytes(base, path);
+      const afterBytes = status === "D" ? 0 : await workingBytes(path);
+      if (beforeBytes > MAX_FILE_BYTES || afterBytes > MAX_FILE_BYTES) {
+        continue;
+      }
+      const before = (status === "A" ? "" : await git(root, ["show", `${base}:${path}`]) ?? "").replace(/\r\n/g, "\n");
+      const after = (status === "D" ? "" : await readWorkingFile(readFile, root, path)).replace(/\r\n/g, "\n");
+      if (before === after) {
+        continue;
+      }
+      const size = Buffer.byteLength(before, "utf8") + Buffer.byteLength(after, "utf8");
+      if (totalBytes + size > MAX_TOTAL_BYTES || looksBinary(before) || looksBinary(after)) {
+        continue;
+      }
+      totalBytes += size;
+      files.push({ path, before, after });
+    }
+    if (files.length === 0) {
+      return null;
+    }
+    const subject = (await git(root, ["log", "-1", "--format=%s", "HEAD"]))?.trim();
+    const fileWord = files.length === 1 ? "file" : "files";
+    const head = label?.trim() || subject || "Working-tree change";
+    const against = fromTrunk ? "vs trunk" : "uncommitted (vs HEAD)";
+    return {
+      description: `${head} (${files.length} ${fileWord} changed ${against})`,
+      files
+    };
+  } catch {
+    return null;
+  }
+}
+async function resolveBase(git, root) {
+  const forced = process.env?.BITFAB_CODE_CHANGE_BASE;
+  if (forced && await refExists(git, root, forced)) {
+    const base = (await git(root, ["merge-base", "HEAD", forced]))?.trim() || (await git(root, ["rev-parse", "--verify", forced]))?.trim() || null;
+    return base ? { base, fromTrunk: true } : null;
+  }
+  for (const candidate of TRUNK_CANDIDATES) {
+    if (!await refExists(git, root, candidate)) {
+      continue;
+    }
+    const mb = (await git(root, ["merge-base", "HEAD", candidate]))?.trim();
+    if (mb) {
+      return { base: mb, fromTrunk: true };
+    }
+  }
+  return await refExists(git, root, "HEAD") ? { base: "HEAD", fromTrunk: false } : null;
+}
+async function refExists(git, root, ref) {
+  return await git(root, ["rev-parse", "--verify", `${ref}^{object}`]) !== null;
+}
+async function readWorkingFile(readFile, root, path) {
+  try {
+    const { join } = await import("path");
+    return await readFile(join(root, path), "utf8");
+  } catch {
+    return "";
+  }
+}
+function parseNameStatusZ(raw) {
+  const parts = raw.split(NUL).filter((p) => p.length > 0);
+  const out = [];
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    out.push({ status: parts[i].charAt(0), path: parts[i + 1] });
+  }
+  return out;
+}
+function looksBinary(s) {
+  return s.slice(0, 8e3).includes(NUL);
+}
+var MAX_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES, TRUNK_CANDIDATES, NUL;
+var init_codeChange = __esm({
+  "src/codeChange.ts"() {
+    "use strict";
+    MAX_FILES = 60;
+    MAX_FILE_BYTES = 5e5;
+    MAX_TOTAL_BYTES = 2e6;
+    TRUNK_CANDIDATES = [
+      "origin/HEAD",
+      "origin/main",
+      "origin/master",
+      "main",
+      "master"
+    ];
+    NUL = String.fromCharCode(0);
+  }
+});
+
+// src/replay.ts
+var replay_exports = {};
+__export(replay_exports, {
+  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
+  replay: () => replay,
+  reportReplayProgress: () => reportReplayProgress
+});
+function dbBranchEnabled(dbBranch) {
+  return dbBranch !== void 0 && dbBranch !== false;
+}
+function resolveDbBranchSettings(dbBranch) {
+  if (!dbBranch || dbBranch === true) {
+    return void 0;
+  }
+  const { minCu, maxCu, warmupSql } = dbBranch;
+  const settings = {
+    ...minCu === void 0 ? {} : { minCu },
+    ...maxCu === void 0 ? {} : { maxCu },
+    ...warmupSql === void 0 ? {} : { warmupSql }
+  };
+  return Object.keys(settings).length === 0 ? void 0 : settings;
+}
+function reportReplayProgress(progress) {
+  const stderr = typeof process !== "undefined" ? process.stderr : void 0;
+  if (!stderr) {
+    return;
+  }
+  try {
+    stderr.write(`${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress)}
+`);
+  } catch {
+  }
+}
+function deserializeInputs(spanData) {
+  const inputMeta = spanData.input_meta;
+  const rawInput = spanData.input;
+  if (inputMeta !== void 0 && inputMeta !== null) {
+    const deserialized = deserializeValue({ json: rawInput, meta: inputMeta });
+    if (Array.isArray(deserialized)) {
+      return deserialized;
+    }
+    return deserialized !== void 0 && deserialized !== null ? [deserialized] : [];
+  }
+  if (Array.isArray(rawInput)) {
+    return rawInput;
+  }
+  return rawInput !== void 0 && rawInput !== null ? [rawInput] : [];
+}
+function deserializeOutput(spanData) {
+  const outputMeta = spanData.output_meta;
+  const rawOutput = spanData.output;
+  if (outputMeta !== void 0 && outputMeta !== null) {
+    return deserializeValue({ json: rawOutput, meta: outputMeta });
+  }
+  return rawOutput;
+}
+function buildMockTree(rootNode) {
+  const spans = /* @__PURE__ */ new Map();
+  const counters = /* @__PURE__ */ new Map();
+  function walk(node) {
+    const key = node.traceFunctionKey;
+    if (key) {
+      const name = node.spanName || key;
+      const counterKey = `${key}:${name}`;
+      const index = counters.get(counterKey) ?? 0;
+      counters.set(counterKey, index + 1);
+      spans.set(`${counterKey}:${index}`, {
+        sourceSpanId: node.sourceSpanId,
+        externalSpanId: node.externalSpanId,
+        output: node.output,
+        outputMeta: node.outputMeta
+      });
+    }
+    for (const child of node.children) {
+      walk(child);
+    }
+  }
+  for (const child of rootNode.children) {
+    walk(child);
+  }
+  return { spans };
+}
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, includeDbBranchLease, dbBranchSettings, adaptInputs) {
+  let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
+  let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
+  let dbSnapshotRef = serverItem.dbSnapshotRef;
+  let inputs = [];
+  let originalOutput;
+  let result;
+  let error = null;
+  const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
+  const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
+  try {
+    if (includeDbBranchLease && !lease && !leaseError) {
+      const resolved = await httpClient.resolveDbBranchLease(
+        testRunId,
+        originalTraceId,
+        dbBranchSettings
+      );
+      lease = resolved.lease ?? void 0;
+      leaseError = resolved.leaseError ?? void 0;
+      dbSnapshotRef = resolved.dbSnapshotRef ?? dbSnapshotRef;
+    }
+    if (leaseError) {
+      throw new BitfabError(
+        `Replay requested a database branch for trace ${originalTraceId} but it could not be resolved (${leaseError.code}): ${leaseError.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`
+      );
+    }
+    const span = await httpClient.getExternalSpan(originalSpanId);
+    const spanData = span.rawData?.span_data ?? {};
+    inputs = deserializeInputs(spanData);
+    originalOutput = deserializeOutput(spanData);
+    if (adaptInputs) {
+      inputs = adaptInputs(inputs, {
+        originalTraceId,
+        originalSpanId,
+        // Deprecated aliases for originalTraceId/originalSpanId.
+        sourceTraceId: originalTraceId,
+        sourceSpanId: originalSpanId
+      });
+    }
+    const hasOverrides = resolvedOverrides.length > 0;
+    const needTree = mockStrategy === "all" || mockStrategy === "marked" || hasOverrides;
+    const includeOutputs = mockStrategy === "all";
+    let mockTree;
+    if (needTree) {
+      try {
+        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 original span ${originalSpanId}.`
+          );
+        } else {
+          mockTree = void 0;
+        }
+      } catch (e) {
+        if (mockStrategy === "all" || hasOverrides) {
+          throw e;
+        }
+        mockTree = void 0;
+      }
+    }
+    const outputCache = /* @__PURE__ */ new Map();
+    const fetchSpanOutput = mockTree && !includeOutputs ? (externalSpanId) => {
+      let pending = outputCache.get(externalSpanId);
+      if (!pending) {
+        pending = httpClient.getExternalSpan(externalSpanId).then(
+          (s) => deserializeOutput(
+            s.rawData?.span_data ?? {}
+          )
+        );
+        outputCache.set(externalSpanId, pending);
+      }
+      return pending;
+    } : void 0;
+    const maybePromise = runWithReplayContext(
+      {
+        testRunId,
+        traceId: replayedTraceId,
+        inputSourceSpanId: span.id,
+        inputSourceTraceId: span.externalTraceId,
+        sourceBitfabTraceId: originalTraceId,
+        mockTree,
+        callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
+        mockStrategy,
+        mockOverrides: hasOverrides ? resolvedOverrides : void 0,
+        fetchSpanOutput,
+        dbBranchLease: lease
+      },
+      () => fn(...inputs)
+    );
+    result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
+  } catch (e) {
+    error = e instanceof Error ? e.message : String(e);
+  } finally {
+    if (lease) {
+      try {
+        await httpClient.releaseDbBranchLease(lease.neonBranchId);
+      } catch (e) {
         try {
-          const out = {};
-          for (const [k, v] of Object.entries(obj)) {
-            out[k] = sanitize(v, seen);
-          }
-          result = out;
-        } catch {
-          warnOnce(
-            "payload:field-getter-threw",
-            "a value with a throwing getter/proxy could not be serialized into a span payload; it was replaced with a placeholder. The span still ships with its other fields intact."
+          console.warn(
+            `Bitfab: failed to release DB branch ${lease.neonBranchId} (TTL janitor will catch it): ${e instanceof Error ? e.message : String(e)}`
           );
-          dropped.push(className);
-          result = `<unserializable: ${className}>`;
+        } catch {
         }
       }
-      seen.delete(obj);
-      return result;
-    };
-    let sanitized;
-    try {
-      sanitized = sanitize(payload, /* @__PURE__ */ new WeakSet());
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return {
-        body: JSON.stringify({ error: `payload_serialize_failed: ${message}` }),
-        dropped
-      };
-    }
-    if (dropped.length > 0 && typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)) {
-      const obj = sanitized;
-      const existing = Array.isArray(obj.errors) ? obj.errors : [];
-      obj.errors = [
-        ...existing,
-        {
-          source: "sdk",
-          step: "json_serialize",
-          error: `stubbed non-serializable value(s): ${[
-            ...new Set(dropped)
-          ].join(", ")}`
-        }
-      ];
     }
-    return { body: JSON.stringify(sanitized), dropped };
   }
+  return {
+    // 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,
+    error,
+    durationMs: serverItem.durationMs ?? null,
+    // Filled in by replay() from the complete-replay response once the
+    // replay traces are persisted and their spans aggregated server-side.
+    // Null here (and on older servers) means "replay tokens not known".
+    tokens: null,
+    model: serverItem.model ?? null,
+    dbSnapshotRef: dbSnapshotRef ?? null
+  };
 }
-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) {
+async function waitForReplayPersistence(httpClient, testRunId, replayedTraceIds) {
+  const deferredSettled = await httpClient.settleDeferredWork(
+    REPLAY_PERSISTENCE_TIMEOUT_MS
+  );
+  if (!deferredSettled) {
+    throw new BitfabError(
+      `Replay could not settle deferred span work before the deadline, so the expected span counts are incomplete (testRunId ${testRunId}).`
+    );
+  }
+  const expectedSpanCounts = takeReplaySpanCounts2(replayedTraceIds);
+  if (Object.keys(expectedSpanCounts).length === 0) {
     return;
   }
-  let timer;
-  try {
-    await Promise.race([
-      Promise.allSettled(Array.from(pendingTracePromises)),
-      new Promise((resolve) => {
-        timer = setTimeout(resolve, timeoutMs);
-        unrefTimer(timer);
-      })
-    ]);
-  } finally {
-    if (timer) {
-      clearTimeout(timer);
+  const flushed = await flushTraces(REPLAY_PERSISTENCE_TIMEOUT_MS);
+  const deadline = Date.now() + REPLAY_PERSISTENCE_TIMEOUT_MS;
+  let missing = Object.keys(expectedSpanCounts).length;
+  while (true) {
+    const status = await httpClient.getReplayStatus(
+      testRunId,
+      expectedSpanCounts
+    );
+    const ready = status.traceIds ?? {};
+    missing = Object.keys(expectedSpanCounts).filter(
+      (traceId) => ready[traceId] === void 0
+    ).length;
+    if (missing === 0) {
+      return;
+    }
+    if (Date.now() >= deadline) {
+      break;
     }
+    await sleep(Math.min(100, Math.max(0, deadline - Date.now())));
   }
+  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}`
+  );
 }
-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;
-      });
-    }
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    unrefTimer(timer);
   });
 }
-var HttpClient = class {
-  constructor(config) {
-    this.apiKey = config.apiKey;
-    this.serviceUrl = config.serviceUrl;
-    this.timeout = config.timeout ?? 12e4;
+async function mapWithConcurrency2(tasks, maxConcurrency, onSettled) {
+  const results = new Array(tasks.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < tasks.length) {
+      const index = nextIndex++;
+      const result = await tasks[index]();
+      results[index] = result;
+      onSettled?.(result, index);
+    }
   }
-  /**
-   * Resolve the API key at the moment it is needed (request time), invoking
-   * the function form if one was supplied. Never read at construction.
-   */
-  resolveApiKey() {
-    return typeof this.apiKey === "function" ? this.apiKey() : this.apiKey;
+  const workers = Array.from(
+    { length: Math.min(maxConcurrency, tasks.length) },
+    () => worker()
+  );
+  await Promise.all(workers);
+  return results;
+}
+async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, registeredOverrides = []) {
+  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}).`
+      );
+    }
   }
-  /**
-   * 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);
-    const { body, dropped } = serializePayloadBody(payload);
-    if (dropped.length > 0) {
-      try {
-        console.warn(
-          `Bitfab: request body to ${endpoint} held ${dropped.length} non-serializable value(s) (${[...new Set(dropped)].join(", ")}); they were stubbed so the span still sends, but the trace may be incomplete or not replayable. Capture a JSON-safe projection of this input to make it replayable.`
-        );
-      } catch {
+  if (options?.limit !== void 0 && options?.traceIds !== void 0) {
+    try {
+      console.warn(
+        "Bitfab: limit is ignored when traceIds is passed: the explicit trace ID list already determines how many traces replay."
+      );
+    } catch {
+    }
+  }
+  await replayContextReady;
+  let codeChangeDescription = options?.codeChangeDescription;
+  let codeChangeFiles = options?.codeChangeFiles;
+  if (codeChangeFiles === void 0) {
+    const captured = await resolveAutoCodeChange(options?.name);
+    if (captured) {
+      codeChangeFiles = captured.files;
+      if (codeChangeDescription === void 0) {
+        codeChangeDescription = captured.description;
       }
     }
-    try {
-      const response = await fetch(url, {
-        method,
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.resolveApiKey() ?? ""}`
-        },
-        body,
-        signal: controller.signal
-      });
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new BitfabError(
-          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
-        );
+  }
+  const {
+    testRunId,
+    testRunUrl,
+    items: serverItems
+  } = await httpClient.startReplay(
+    traceFunctionKey,
+    // 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?.name,
+    codeChangeDescription,
+    codeChangeFiles,
+    dbBranchEnabled(options?.dbBranch),
+    // includeDbBranchLease
+    options?.experimentGroupId,
+    options?.datasetId,
+    options?.graderIds,
+    resolveDbBranchSettings(options?.dbBranch)
+  );
+  const mockStrategy = options?.mock ?? "marked";
+  const maxConcurrency = options?.maxConcurrency ?? 10;
+  const resolvedOverrides = [
+    ...normalizeMockOverrides(options?.mockOverride),
+    ...registeredOverrides
+  ];
+  const replayedTraceIds = serverItems.map(() => randomUuid());
+  const tasks = serverItems.map(
+    (serverItem, index) => () => processItem(
+      httpClient,
+      serverItem,
+      fn,
+      testRunId,
+      mockStrategy,
+      resolvedOverrides,
+      replayedTraceIds[index],
+      dbBranchEnabled(options?.dbBranch),
+      resolveDbBranchSettings(options?.dbBranch),
+      options?.adaptInputs
+    )
+  );
+  const total = tasks.length;
+  let completed = 0;
+  let succeeded = 0;
+  let errored = 0;
+  const resultItems = await mapWithConcurrency2(
+    tasks,
+    maxConcurrency,
+    options?.onProgress ? (item) => {
+      completed += 1;
+      if (item.error === null) {
+        succeeded += 1;
+      } else {
+        errored += 1;
       }
-      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
-          );
+      try {
+        options?.onProgress?.({
+          testRunId,
+          completed,
+          total,
+          succeeded,
+          errored,
+          item: {
+            // 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,
+            error: item.error,
+            durationMs: item.durationMs,
+            tokens: item.tokens,
+            model: item.model,
+            dbSnapshotRef: item.dbSnapshotRef
+          }
+        });
+      } catch {
+      }
+    } : void 0
+  );
+  await waitForReplayPersistence(httpClient, testRunId, replayedTraceIds);
+  const completeResult = await httpClient.completeReplay(testRunId);
+  const serverTraceIds = completeResult.traceIds;
+  const replayTokens = completeResult.tokens;
+  if (serverTraceIds !== void 0) {
+    const missing = [];
+    let completedCount = 0;
+    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);
         }
-        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);
+      if (mapped !== void 0) {
+        item.tokens = replayTokens?.[mapped] ?? null;
       }
-      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 });
-  }
-  async getTraceSpan(traceId, lookup) {
-    const searchParams = new URLSearchParams();
-    if (lookup.id !== void 0) {
-      searchParams.set("id", lookup.id);
-    } else {
-      searchParams.set("name", lookup.name);
-      searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
     }
-    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
-    const response = await this.get(endpoint);
-    return response.span;
-  }
-  async get(endpoint) {
-    const url = `${this.serviceUrl}${endpoint}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method: "GET",
-        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
-        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 ${this.timeout}ms`);
-        }
-        throw new BitfabError(error.message);
-      }
-      throw new BitfabError("Unknown error occurred");
-    } finally {
-      clearTimeout(timeoutId);
+    if (completedCount > 0 && missing.length === completedCount) {
+      const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
+      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.`
+      );
     }
-  }
-  /**
-   * 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 trace identified by its Bitfab trace ID.
-   * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
-   * returns a tracked promise that callers may optionally await.
-   */
-  patchTrace(traceId, payload) {
-    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}`;
-    return awaitOnExit(
-      this.request(endpoint, payload, { method: "PATCH" })
-    ).catch((error) => {
+    if (missing.length > 0) {
       try {
-        console.error("Bitfab: Failed to patch trace:", error);
+        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.`
+        );
       } 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, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings) {
-    const payload = { traceFunctionKey };
-    if (limit !== void 0) {
-      payload.limit = limit;
-    }
-    if (traceIds) {
-      payload.traceIds = traceIds;
-    }
-    if (name !== void 0) {
-      payload.name = name;
-    }
-    if (codeChangeDescription !== void 0) {
-      payload.codeChangeDescription = codeChangeDescription;
-    }
-    if (codeChangeFiles !== void 0) {
-      payload.codeChangeFiles = codeChangeFiles;
-    }
-    if (includeDbBranchLease) {
-      payload.includeDbBranchLease = true;
-      payload.lazyDbBranchLease = true;
     }
-    if (experimentGroupId !== void 0) {
-      payload.experimentGroupId = experimentGroupId;
-    }
-    if (datasetId !== void 0) {
-      payload.datasetId = datasetId;
-    }
-    if (graderIds !== void 0) {
-      payload.graderIds = graderIds;
-    }
-    if (dbBranchSettings !== void 0) {
-      payload.dbBranchSettings = dbBranchSettings;
-    }
-    const timeout = includeDbBranchLease ? REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS : 3e4;
-    return this.request("/api/sdk/replay/start", payload, {
-      timeout
+  }
+  const result = {
+    items: resultItems,
+    testRunId,
+    testRunUrl: `${serviceUrl}${testRunUrl}`
+  };
+  await writeReplayResultFile(result);
+  try {
+    options?.onProgress?.({
+      type: "complete",
+      testRunId,
+      completed: total,
+      total,
+      succeeded,
+      errored,
+      result
     });
+  } catch {
   }
-  /**
-   * 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.resolveApiKey() ?? ""}` },
-        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);
-    }
+  return result;
+}
+async function writeReplayResultFile(result) {
+  const resultPath = typeof process !== "undefined" ? process.env?.BITFAB_REPLAY_RESULT_PATH : void 0;
+  if (!resultPath) {
+    return;
   }
-  /**
-   * Fetch the span tree for a root span.
-   * Blocking GET request.
-   *
-   * Pass `includeOutputs: false` for a payload-free tree (structure +
-   * `externalSpanId` only), so recorded outputs are fetched lazily per mocked
-   * span instead of all up front. Omit it (default eager) for `mock: "all"`.
-   */
-  async getSpanTree(externalSpanId, options) {
-    const query = options?.includeOutputs === false ? "?includeOutputs=false" : "";
-    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}${query}`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+  try {
+    const [{ dirname }, { mkdir, writeFile }] = await Promise.all([
+      import("path"),
+      import("fs/promises")
+    ]);
+    await mkdir(dirname(resultPath), { recursive: true });
+    await writeFile(resultPath, `${JSON.stringify(result, null, 2)}
+`);
+  } catch (err) {
     try {
-      const response = await fetch(url, {
-        method: "GET",
-        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
-        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);
+      console.warn(
+        `Bitfab: failed to write replay result to BITFAB_REPLAY_RESULT_PATH (${resultPath}): ${err instanceof Error ? err.message : String(err)}`
+      );
+    } catch {
     }
   }
-  /**
-   * 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, dbBranchSettings) {
-    return this.request(
-      "/api/sdk/replay/resolveDbBranchLease",
-      { testRunId, traceId, dbBranchSettings },
-      { timeout: REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS }
-    );
-  }
-  /** 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 }
-    );
+}
+var REPLAY_PERSISTENCE_TIMEOUT_MS, BITFAB_PROGRESS_PREFIX;
+var init_replay = __esm({
+  "src/replay.ts"() {
+    "use strict";
+    init_codeChange();
+    init_errors();
+    init_http();
+    init_mockOverride();
+    init_randomUuid();
+    init_replayContext();
+    init_serialize();
+    init_transport();
+    init_unrefTimer();
+    REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
+    BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
   }
-};
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BITFAB_PROGRESS_PREFIX: () => BITFAB_PROGRESS_PREFIX,
+  Bitfab: () => Bitfab,
+  BitfabClaudeAgentHandler: () => BitfabClaudeAgentHandler,
+  BitfabError: () => BitfabError,
+  BitfabFunction: () => BitfabFunction,
+  BitfabLangChainCallbackHandler: () => BitfabLangGraphCallbackHandler,
+  BitfabLangGraphCallbackHandler: () => BitfabLangGraphCallbackHandler,
+  BitfabOpenAIAgentHandler: () => BitfabOpenAIAgentHandler,
+  BitfabOpenAITracingProcessor: () => BitfabOpenAITracingProcessor,
+  BitfabVercelAiHandler: () => BitfabVercelAiHandler,
+  DEFAULT_SERVICE_URL: () => DEFAULT_SERVICE_URL,
+  SUPPORTED_PROVIDERS: () => SUPPORTED_PROVIDERS,
+  __version__: () => __version__,
+  finalizers: () => finalizers,
+  flushTraces: () => flushTraces,
+  getCurrentReplayBranch: () => getCurrentReplayBranch,
+  getCurrentSpan: () => getCurrentSpan,
+  getCurrentTrace: () => getCurrentTrace,
+  reportReplayProgress: () => reportReplayProgress
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/claudeAgentSdk.ts
+init_constants();
+init_http();
 
 // src/processorPayload.ts
 init_serialize();
@@ -1640,7 +2568,8 @@ var BitfabClaudeAgentHandler = class {
     // its root. The prompt is not present anywhere in the message stream, so it
     // must be handed in explicitly.
     this.hasRootInput = false;
-    this.httpClient = new HttpClient({
+    this.ownsHttpClient = config._httpClient === void 0;
+    this.httpClient = config._httpClient ?? new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
       timeout: config.timeout ?? 1e4
@@ -1653,6 +2582,14 @@ var BitfabClaudeAgentHandler = class {
     this.subagentStartHook = this.subagentStartHook.bind(this);
     this.subagentStopHook = this.subagentStopHook.bind(this);
   }
+  /**
+   * Flush and release the span transport this handler started. A no-op when
+   * the handler borrowed a `Bitfab` client's HTTP client: that client's
+   * `close()` owns the worker's lifetime.
+   */
+  async close(timeoutMs) {
+    return this.ownsHttpClient ? this.httpClient.close(timeoutMs) : true;
+  }
   // ── trace lifecycle ──────────────────────────────────────────
   ensureTrace() {
     if (this.traceId !== null) {
@@ -2423,6 +3360,9 @@ async function runFunctionWithBaml(bamlSource, inputs, providers, envVars) {
   };
 }
 
+// src/client.ts
+init_constants();
+
 // src/dbSnapshot.ts
 init_errors();
 var SUPPORTED_PROVIDERS = ["neon"];
@@ -2440,7 +3380,12 @@ function buildSnapshotRef(config, sdkWallClockBeforeFn) {
   };
 }
 
+// src/client.ts
+init_http();
+
 // src/langgraph.ts
+init_constants();
+init_http();
 init_randomUuid();
 init_serialize();
 var LANGSMITH_HIDDEN_TAG = "langsmith:hidden";
@@ -2664,7 +3609,8 @@ var BitfabLangGraphCallbackHandler = class {
     this.ignoreCustomEvent = true;
     this.runToSpan = /* @__PURE__ */ new Map();
     this.invocations = /* @__PURE__ */ new Map();
-    this.httpClient = new HttpClient({
+    this.ownsHttpClient = config._httpClient === void 0;
+    this.httpClient = config._httpClient ?? new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
       timeout: config.timeout ?? 1e4
@@ -2672,6 +3618,14 @@ var BitfabLangGraphCallbackHandler = class {
     this.traceFunctionKey = config.traceFunctionKey;
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
   }
+  /**
+   * Flush and release the span transport this handler started. A no-op when
+   * the handler borrowed a `Bitfab` client's HTTP client: that client's
+   * `close()` owns the worker's lifetime.
+   */
+  async close(timeoutMs) {
+    return this.ownsHttpClient ? this.httpClient.close(timeoutMs) : true;
+  }
   // ── lifecycle helpers ──────────────────────────────────────────
   startSpan(runId, parentRunId, name, spanType, inputData, metadata, tags) {
     const parentSpan = parentRunId ? this.runToSpan.get(parentRunId) : void 0;
@@ -2756,7 +3710,9 @@ var BitfabLangGraphCallbackHandler = class {
     if (extraContexts && Object.keys(extraContexts).length > 0) {
       spanInfo.contexts.push(extraContexts);
     }
-    this.sendSpan(spanInfo);
+    if (spanInfo.hidden !== true) {
+      this.sendSpan(spanInfo);
+    }
     if (runId === spanInfo.rootRunId) {
       const invocation = this.invocations.get(runId);
       this.sendTraceCompletion(spanInfo, invocation?.activeContext ?? null);
@@ -2780,9 +3736,6 @@ var BitfabLangGraphCallbackHandler = class {
     if (spanInfo.contexts.length > 0) {
       spanData.contexts = spanInfo.contexts;
     }
-    if (spanInfo.hidden) {
-      spanData.hidden = true;
-    }
     const rawSpan = {
       id: spanInfo.spanId,
       trace_id: spanInfo.traceId,
@@ -3144,6 +4097,8 @@ init_replayContext();
 init_serialize();
 
 // src/tracing.ts
+init_constants();
+init_http();
 init_randomUuid();
 var BitfabOpenAITracingProcessor = class {
   /**
@@ -3155,7 +4110,8 @@ var BitfabOpenAITracingProcessor = class {
     this.activeTraces = {};
     this.activeSpanMappings = {};
     this.canonicalTraceIds = {};
-    this.httpClient = new HttpClient({
+    this.ownsHttpClient = config._httpClient === void 0;
+    this.httpClient = config._httpClient ?? new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
       timeout: config.timeout ?? 1e4
@@ -3171,6 +4127,14 @@ var BitfabOpenAITracingProcessor = class {
     this.canonicalTraceIds[sourceTraceId] = created;
     return created;
   }
+  /**
+   * Flush and release the span transport this processor started. A no-op when
+   * the processor borrowed a `Bitfab` client's HTTP client: that client's
+   * `close()` owns the worker's lifetime.
+   */
+  async close(timeoutMs) {
+    return this.ownsHttpClient ? this.httpClient.close(timeoutMs) : true;
+  }
   /**
    * Called when a trace is started.
    * If there's an active withSpan context, the trace ID is remapped to the
@@ -3225,14 +4189,16 @@ var BitfabOpenAITracingProcessor = class {
    * Called when a trace is being flushed.
    */
   async forceFlush() {
+    await this.httpClient.waitForPendingRequests();
   }
   /**
    * Called when the trace processor is shutting down.
    */
-  async shutdown(_timeout) {
+  async shutdown(timeout) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
     this.canonicalTraceIds = {};
+    await this.close(timeout);
   }
   /**
    * Send trace to Bitfab API (fire-and-forget).
@@ -3499,7 +4465,6 @@ var BitfabVercelAiHandler = class {
 // src/client.ts
 init_warnOnce();
 var activeTraceStates = /* @__PURE__ */ new Map();
-var pendingSpanPromises = /* @__PURE__ */ new Map();
 var asyncLocalStorage = null;
 var SPAN_CONTEXT_STORAGE_SYMBOL = /* @__PURE__ */ Symbol.for("bitfab.spanContextStorage");
 var initializeAsyncContext = () => {
@@ -3817,7 +4782,7 @@ function getCurrentTrace() {
     }
   };
 }
-function readEnv(name) {
+function readEnv2(name) {
   if (typeof process !== "undefined" && process.env) {
     return process.env[name];
   }
@@ -3855,6 +4820,23 @@ var Bitfab = class {
       timeout: this.timeout
     });
   }
+  /**
+   * Flush and permanently close this client's tracing resources: its pending
+   * requests and the single span-transport worker shared by its decorators and
+   * framework handlers.
+   *
+   * Resolves `false` when delivery failed or the deadline expired. Long-lived
+   * processes never need this (the transport batches in the background and the
+   * exit hook drains it); scripts and tests that want a hard guarantee should
+   * await it.
+   *
+   * Deliberately not a `Symbol.asyncDispose` method: the SDK targets runtimes
+   * where that symbol may be absent, and a computed key on a missing symbol
+   * throws at class-definition time, taking the whole SDK down on load.
+   */
+  close(timeoutMs) {
+    return this.httpClient.close(timeoutMs);
+  }
   /**
    * Resolve the API key lazily, the first time a span actually needs it.
    *
@@ -3875,7 +4857,7 @@ var Bitfab = class {
       return this.resolvedApiKey;
     }
     const fromConfig = typeof this.apiKeyConfig === "function" ? this.apiKeyConfig() : this.apiKeyConfig;
-    const candidate = fromConfig && fromConfig.trim() !== "" ? fromConfig : readEnv("BITFAB_API_KEY");
+    const candidate = fromConfig && fromConfig.trim() !== "" ? fromConfig : readEnv2("BITFAB_API_KEY");
     const key = candidate && candidate.trim() !== "" ? candidate : void 0;
     if (key) {
       this.resolvedApiKey = key;
@@ -4004,7 +4986,8 @@ var Bitfab = class {
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;
-      }
+      },
+      _httpClient: this.httpClient
     });
   }
   /**
@@ -4064,7 +5047,8 @@ var Bitfab = class {
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;
-      }
+      },
+      _httpClient: this.httpClient
     });
   }
   /**
@@ -4116,7 +5100,8 @@ var Bitfab = class {
       getActiveSpanContext: () => {
         const stack = getSpanStack();
         return stack[stack.length - 1] ?? null;
-      }
+      },
+      _httpClient: this.httpClient
     });
   }
   /**
@@ -4369,7 +5354,6 @@ var Bitfab = class {
             },
             dbSnapshotRef
           });
-          pendingSpanPromises.set(traceId, []);
           registeredTraceId = traceId;
         }
         const functionName = fn.name !== "" ? fn.name : void 0;
@@ -4384,57 +5368,29 @@ var Bitfab = class {
           startedAt,
           spanType: options.type ?? "custom"
         };
-        const sendSpan = async (params, spanOpts) => {
+        const sendSpan = async (params) => {
           const replayCtx = getReplayContext();
-          const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
-          let resolvePersistence;
-          if (persistenceCollector && !spanOpts?.skipPersistenceRegistration) {
-            persistenceCollector.push(
-              new Promise((resolve) => {
-                resolvePersistence = resolve;
-              })
-            );
-          }
           try {
             const endedAt = (/* @__PURE__ */ new Date()).toISOString();
             const traceDropped = activeTraceStates.get(traceId)?.dropped === true;
-            const spanPromise = traceDropped ? Promise.resolve() : self.sendWrapperSpan({
-              ...baseSpanParams,
-              ...params,
-              contexts: newContext.contexts,
-              prompt: newContext.prompt,
-              endedAt,
-              ...replayCtx?.testRunId && {
-                testRunId: replayCtx.testRunId
-              },
-              ...replayCtx?.inputSourceSpanId && {
-                inputSourceSpanId: replayCtx.inputSourceSpanId
-              }
-            });
-            if (isRootSpan) {
-              const pending = pendingSpanPromises.get(traceId) ?? [];
-              pending.push(spanPromise);
-              if (persistenceCollector) {
-                await Promise.allSettled(pending);
-              } else {
-                let raceTimer;
-                try {
-                  await Promise.race([
-                    Promise.allSettled(pending),
-                    new Promise((resolve) => {
-                      raceTimer = setTimeout(resolve, 5e3);
-                      unrefTimer(raceTimer);
-                    })
-                  ]);
-                } finally {
-                  if (raceTimer) {
-                    clearTimeout(raceTimer);
-                  }
+            if (!traceDropped) {
+              self.sendWrapperSpan({
+                ...baseSpanParams,
+                ...params,
+                contexts: newContext.contexts,
+                prompt: newContext.prompt,
+                endedAt,
+                ...replayCtx?.testRunId && {
+                  testRunId: replayCtx.testRunId
+                },
+                ...replayCtx?.inputSourceSpanId && {
+                  inputSourceSpanId: replayCtx.inputSourceSpanId
                 }
-              }
-              pendingSpanPromises.delete(traceId);
+              });
+            }
+            if (isRootSpan) {
               const traceState = activeTraceStates.get(traceId);
-              const completionPromise = self.sendTraceCompletion({
+              self.sendTraceCompletion({
                 traceFunctionKey,
                 traceId,
                 startedAt: traceState?.startedAt ?? startedAt,
@@ -4460,20 +5416,8 @@ var Bitfab = class {
                 }
               });
               activeTraceStates.delete(traceId);
-              if (persistenceCollector) {
-                await completionPromise;
-              }
-            } else {
-              const pending = pendingSpanPromises.get(traceId);
-              if (pending) {
-                pending.push(spanPromise);
-              } else {
-                pendingSpanPromises.set(traceId, [spanPromise]);
-              }
             }
           } catch {
-          } finally {
-            resolvePersistence?.();
           }
         };
         const replayCtxForMock = getReplayContext();
@@ -4557,30 +5501,14 @@ var Bitfab = class {
         }
         const recordSpan = (result) => {
           if (options.finalize) {
-            const replayCtx = getReplayContext();
-            const persistenceCollector = isRootSpan ? replayCtx?.pendingPersistence : void 0;
-            let resolvePersistence;
-            if (persistenceCollector) {
-              persistenceCollector.push(
-                new Promise((resolve) => {
-                  resolvePersistence = resolve;
-                })
-              );
-            }
-            void Promise.resolve().then(() => options.finalize(result)).then(
-              (output) => sendSpan(
-                { result: output },
-                { skipPersistenceRegistration: true }
-              )
-            ).catch(
-              (error) => sendSpan(
-                {
+            void self.httpClient.trackDeferred(
+              Promise.resolve().then(() => options.finalize(result)).then((output) => sendSpan({ result: output })).catch(
+                (error) => sendSpan({
                   result: void 0,
                   error: error instanceof Error ? `finalize failed: ${error.message}` : `finalize failed: ${String(error)}`
-                },
-                { skipPersistenceRegistration: true }
+                })
               )
-            ).finally(() => resolvePersistence?.());
+            );
           } else {
             void sendSpan({ result });
           }
@@ -4608,7 +5536,6 @@ var Bitfab = class {
       } catch (setupError) {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
-          pendingSpanPromises.delete(registeredTraceId);
         }
         if (getReplayContext()) {
           throw setupError;
@@ -4731,7 +5658,7 @@ var Bitfab = class {
   /**
    * Send trace completion when a root span ends.
    * Internal method to record trace completion with end time.
-   * Fire-and-forget - sends to externalTraces endpoint via httpClient.
+   * Queued on the client's span transport; delivery is the transport's job.
    */
   sendTraceCompletion(params) {
     const rawTrace = {
@@ -4767,7 +5694,7 @@ var Bitfab = class {
         accessed: params.dbSnapshotUsage.accessed
       };
     }
-    return this.httpClient.sendExternalTrace({
+    this.httpClient.sendExternalTrace({
       id: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
@@ -4782,7 +5709,7 @@ var Bitfab = class {
   /**
    * Send a wrapper span from function execution.
    * Internal method to record spans when using withSpan.
-   * Fire-and-forget - sends to externalSpans endpoint via httpClient.
+   * Queued on the client's span transport; delivery is the transport's job.
    */
   sendWrapperSpan(params) {
     const serializedInputs = serializeValue(params.inputs);
@@ -4823,7 +5750,7 @@ var Bitfab = class {
     if (params.inputSourceSpanId) {
       externalSpan.input_source_span_id = params.inputSourceSpanId;
     }
-    return this.httpClient.sendExternalSpan({
+    this.httpClient.sendExternalSpan({
       id: params.spanId,
       traceId: params.traceId,
       type: "sdk-function",
@@ -5012,6 +5939,9 @@ var BitfabFunction = class {
   }
 };
 
+// src/index.ts
+init_constants();
+
 // src/finalizers.ts
 async function settle(value) {
   try {
@@ -5061,6 +5991,7 @@ var finalizers = {
 };
 
 // src/index.ts
+init_http();
 init_replay();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {