bitfab 0.13.5 → 0.13.6

package/dist/node.js

@@ -17,7 +17,7 @@ import {
   SUPPORTED_PROVIDERS,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-4IHJJRMU.js";
+} from "./chunk-6757PVPS.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -25,7 +25,7 @@ import {
   assertAsyncStorageRegistered,
   flushTraces,
   registerAsyncLocalStorageClass
-} from "./chunk-BVFST7Q3.js";
+} from "./chunk-TMSVIA5J.js";
 
 // src/asyncStorageNode.ts
 import { AsyncLocalStorage } from "async_hooks";

package/dist/{replay-CLQKO7U7.js → replay-UBXCO6QU.js}

@@ -3,7 +3,7 @@ import {
   flushTraces,
   replayContextReady,
   runWithReplayContext
-} from "./chunk-BVFST7Q3.js";
+} from "./chunk-TMSVIA5J.js";
 
 // src/replay.ts
 function deserializeInputs(spanData) {
@@ -144,8 +144,9 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
     options?.traceIds,
     options?.codeChangeDescription,
     options?.codeChangeFiles,
-    options?.environment !== void 0
+    options?.environment !== void 0,
     // includeDbBranchLease
+    options?.experimentGroupId
   );
   const mockStrategy = options?.mock ?? "none";
   const maxConcurrency = options?.maxConcurrency ?? 10;
@@ -185,4 +186,4 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options) {
 export {
   replay
 };
-//# sourceMappingURL=replay-CLQKO7U7.js.map
+//# sourceMappingURL=replay-UBXCO6QU.js.map

package/dist/replay-UBXCO6QU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/replay.ts"],"sourcesContent":["/**\n * Replay historical traces through a function and create a test run.\n *\n * The replay flow has three phases:\n * 1. Start — fetches historical traces from the server and creates a test run\n * 2. Execute — re-runs each trace's inputs through the provided function locally\n * 3. Complete — marks the test run as completed on the server\n */\n\nimport type { DbSnapshotRef } from \"./dbSnapshot.js\"\nimport type {\n  CodeChangeFile,\n  HttpClient,\n  SpanTreeNode,\n  TokenUsage,\n} from \"./http.js\"\nimport { flushTraces } from \"./http.js\"\nimport type { DbBranchLease, MockTree } from \"./replayContext.js\"\nimport { replayContextReady, runWithReplayContext } from \"./replayContext.js\"\nimport type { ReplayEnvironment } from \"./replayEnvironment.js\"\nimport { deserializeValue } from \"./serialize.js\"\n\nexport type MockStrategy = \"none\" | \"all\" | \"marked\"\n\nexport interface ReplayOptions {\n  /** Maximum number of traces to replay (1–100, default 5). */\n  limit?: number\n  /** Optional list of specific trace IDs to replay. */\n  traceIds?: string[]\n  /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */\n  maxConcurrency?: number\n  /**\n   * Description of the code change being tested in this replay. Stored on\n   * the resulting experiment so the change can be reviewed alongside results.\n   */\n  codeChangeDescription?: string\n  /**\n   * Files edited as part of this code change. Each entry holds the file path\n   * and the full `before`/`after` contents — the agent reads each file before\n   * and after editing and passes the two strings. Use `\"\"` for newly created\n   * files (`before`) or deleted files (`after`).\n   */\n  codeChangeFiles?: CodeChangeFile[]\n  /**\n   * Mock strategy for child spans during replay.\n   * - \"none\": everything runs real code (default)\n   * - \"all\": every child withSpan returns historical output\n   * - \"marked\": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked\n   */\n  mock?: MockStrategy\n  /**\n   * Per-trace environment. When the source trace carries a DB branching\n   * snapshot, the SDK populates `environment.databaseUrl` before invoking\n   * `fn` for that item and resets it after. Customer code reads from the\n   * environment to pick up the per-trace branch URL.\n   */\n  environment?: ReplayEnvironment\n  /** Group ID to associate this replay with an experiment group for live streaming in Studio. */\n  experimentGroupId?: string\n}\n\nexport interface ReplayItem<T> {\n  /** Trace ID of the new trace created during replay. */\n  traceId: string | null\n  /** Deserialized inputs from the original trace. */\n  input: unknown[]\n  /** The result returned by the function during replay, or undefined on error. */\n  result: T | undefined\n  /** The original output from the historical trace. */\n  originalOutput: unknown\n  /** Error message if the function threw, or null on success. */\n  error: string | null\n  /** Original trace duration in milliseconds, or null if timestamps are missing. */\n  durationMs: number | null\n  /** Token usage from the original trace, or null if not captured. */\n  tokens: TokenUsage | null\n  /** Model name from the original trace, or null if not captured. */\n  model: string | null\n  /**\n   * The DB snapshot ref the SDK captured at trace open. Useful for debugging\n   * (\"what state was this trace pinned to?\") and for customers building\n   * their own resolvers. Undefined when the source trace was captured\n   * without `dbSnapshot` configured.\n   */\n  dbSnapshotRef: DbSnapshotRef | null\n}\n\nexport type { CodeChangeFile, TokenUsage }\n\nexport interface ReplayResult<T> {\n  /** Individual replay items with inputs, results, and comparison data. */\n  items: ReplayItem<T>[]\n  /** The test run ID created on the server. */\n  testRunId: string\n  /** Full URL to view the test run in the dashboard. */\n  testRunUrl: string\n}\n\n/**\n * Deserialize inputs from a historical span's rawData.\n *\n * Prefers superjson-serialized `input_meta` for type preservation,\n * falls back to the raw `input` field.\n */\nfunction deserializeInputs(spanData: Record<string, unknown>): unknown[] {\n  const inputMeta = spanData.input_meta as unknown\n  const rawInput = spanData.input\n\n  // If superjson meta is available, deserialize with type reconstruction\n  if (inputMeta !== undefined && inputMeta !== null) {\n    const deserialized = deserializeValue({ json: rawInput, meta: inputMeta })\n    if (Array.isArray(deserialized)) {\n      return deserialized\n    }\n    return deserialized !== undefined && deserialized !== null\n      ? [deserialized]\n      : []\n  }\n\n  // Fall back to raw input\n  if (Array.isArray(rawInput)) {\n    return rawInput\n  }\n  return rawInput !== undefined && rawInput !== null ? [rawInput] : []\n}\n\n/**\n * Deserialize the original output from a historical span's rawData.\n */\nfunction deserializeOutput(spanData: Record<string, unknown>): unknown {\n  const outputMeta = spanData.output_meta as unknown\n  const rawOutput = spanData.output\n\n  if (outputMeta !== undefined && outputMeta !== null) {\n    return deserializeValue({ json: rawOutput, meta: outputMeta })\n  }\n\n  return rawOutput\n}\n\n/**\n * Walk the children of a root span tree node in depth-first order and build\n * a MockTree keyed by `${traceFunctionKey}:${spanName}:${callIndex}`.\n *\n * The historical root itself is NOT walked. At replay time the runtime root\n * span has `isRootSpan === true` and never queries the mockTree (mock\n * interception is skipped for root spans by design), so the root has nothing\n * to look up. Walking it would just leave an unreachable entry in the table.\n *\n * The (key, name) compound match is what disambiguates same-key spans:\n *   - A wrapped function's children commonly share its traceFunctionKey via\n *     the fluent `getFunction(key).withSpan({ name }, ...)` pattern. They\n *     disambiguate by `name`, never colliding with each other.\n *   - Recursion: same (key, name) at every depth. callIndex per (key, name)\n *     orders them correctly without leaking the historical root into the\n *     nested call's slot.\n *   - Outer-wrapper replay scripts: the outer wrapper's `name` is distinct\n *     from anything in the historical tree (it only exists at replay), so\n *     its presence never disturbs counters or lookups for spans that do\n *     exist in the historical tree.\n */\nfunction buildMockTree(rootNode: SpanTreeNode): MockTree {\n  const spans = new Map<\n    string,\n    { sourceSpanId: string; output: unknown; outputMeta?: unknown }\n  >()\n  const counters = new Map<string, number>()\n\n  function walk(node: SpanTreeNode): void {\n    const key = node.traceFunctionKey\n    if (key) {\n      const name = node.spanName\n      const counterKey = `${key}:${name}`\n      const index = counters.get(counterKey) ?? 0\n      counters.set(counterKey, index + 1)\n      spans.set(`${counterKey}:${index}`, {\n        sourceSpanId: node.sourceSpanId,\n        output: node.output,\n        outputMeta: node.outputMeta,\n      })\n    }\n    for (const child of node.children) {\n      walk(child)\n    }\n  }\n\n  for (const child of rootNode.children) {\n    walk(child)\n  }\n\n  return { spans }\n}\n\n/**\n * Execute a single replay item: fetch span data, deserialize inputs, call\n * the function within a replay context that injects testRunId into new spans.\n */\nasync function processItem<TReturn>(\n  httpClient: HttpClient,\n  serverItem: {\n    traceId: string\n    externalSpanId: string\n    durationMs: number | null\n    tokens: TokenUsage | null\n    model: string | null\n    dbSnapshotRef?: DbSnapshotRef\n    dbBranchLease?: DbBranchLease\n  },\n  // biome-ignore lint/suspicious/noExplicitAny: replay deserializes inputs from historical data\n  fn: (...args: any[]) => TReturn | Promise<TReturn>,\n  testRunId: string,\n  mockStrategy: MockStrategy,\n  environment: ReplayEnvironment | undefined,\n): Promise<ReplayItem<TReturn>> {\n  // The server-side resolver materializes a Neon preview branch per item\n  // during `/api/sdk/replay/start` (when the customer passed `environment`,\n  // which triggers `includeDbBranchLease: true`). The lease arrives on the\n  // server item; we just attach it to the replay context and release the\n  // branch in `finally` so any throw — in fetch, mock-tree build, or the\n  // customer fn — frees the Neon resource. Items whose source trace had\n  // no snapshot ref, or whose resolve failed server-side, arrive without\n  // a lease; `env.active` will be `false` for those.\n  const lease = environment ? serverItem.dbBranchLease : undefined\n\n  let inputs: unknown[] = []\n  let originalOutput: unknown\n  let result: TReturn | undefined\n  let error: string | null = null\n  const replayedTraceId = crypto.randomUUID()\n\n  try {\n    const span = await httpClient.getExternalSpan(serverItem.externalSpanId)\n    const spanData = (span.rawData?.span_data ?? {}) as Record<string, unknown>\n\n    inputs = deserializeInputs(spanData)\n    originalOutput = deserializeOutput(spanData)\n\n    // Build mock tree when mocking is active\n    let mockTree: MockTree | undefined\n    if (mockStrategy === \"all\" || mockStrategy === \"marked\") {\n      const treeResponse = await httpClient.getSpanTree(\n        serverItem.externalSpanId,\n      )\n      mockTree = buildMockTree(treeResponse.root)\n    }\n\n    const maybePromise = runWithReplayContext(\n      {\n        testRunId,\n        traceId: replayedTraceId,\n        inputSourceSpanId: span.id,\n        inputSourceTraceId: span.externalTraceId,\n        sourceBitfabTraceId: serverItem.traceId,\n        mockTree,\n        callCounters: mockTree ? new Map() : undefined,\n        mockStrategy,\n        dbBranchLease: lease,\n      },\n      () => fn(...inputs),\n    )\n    result = maybePromise instanceof Promise ? await maybePromise : maybePromise\n  } catch (e) {\n    error = e instanceof Error ? e.message : String(e)\n  } finally {\n    if (lease) {\n      try {\n        await httpClient.releaseDbBranchLease(lease.leaseId)\n      } catch (e) {\n        try {\n          console.warn(\n            `Bitfab: failed to release DB branch lease ${lease.leaseId} (TTL janitor will catch it): ${\n              e instanceof Error ? e.message : String(e)\n            }`,\n          )\n        } catch {\n          // Never crash the host\n        }\n      }\n    }\n  }\n\n  return {\n    traceId: replayedTraceId,\n    input: inputs,\n    result,\n    originalOutput,\n    error,\n    durationMs: serverItem.durationMs ?? null,\n    tokens: serverItem.tokens ?? null,\n    model: serverItem.model ?? null,\n    dbSnapshotRef: serverItem.dbSnapshotRef ?? null,\n  }\n}\n\n/**\n * Run async tasks with a concurrency limit.\n * Each task factory is called when a slot opens; results preserve input order.\n */\nasync function mapWithConcurrency<T>(\n  tasks: Array<() => Promise<T>>,\n  maxConcurrency: number,\n): Promise<T[]> {\n  const results: T[] = new Array(tasks.length)\n  let nextIndex = 0\n\n  async function worker(): Promise<void> {\n    while (nextIndex < tasks.length) {\n      const index = nextIndex++\n      results[index] = await tasks[index]()\n    }\n  }\n\n  const workers = Array.from(\n    { length: Math.min(maxConcurrency, tasks.length) },\n    () => worker(),\n  )\n  await Promise.all(workers)\n  return results\n}\n\n/**\n * Replay historical traces through a function and create a test run.\n *\n * @internal Called by Bitfab.replay — not part of the public API.\n */\nexport async function replay<TReturn>(\n  httpClient: HttpClient,\n  serviceUrl: string,\n  traceFunctionKey: string,\n  // biome-ignore lint/suspicious/noExplicitAny: replay deserializes inputs from historical data\n  fn: (...args: any[]) => TReturn | Promise<TReturn>,\n  options?: ReplayOptions,\n): Promise<ReplayResult<TReturn>> {\n  await replayContextReady\n\n  const {\n    testRunId,\n    testRunUrl,\n    items: serverItems,\n  } = await httpClient.startReplay(\n    traceFunctionKey,\n    options?.limit ?? 5,\n    options?.traceIds,\n    options?.codeChangeDescription,\n    options?.codeChangeFiles,\n    options?.environment !== undefined, // includeDbBranchLease\n    options?.experimentGroupId,\n  )\n\n  const mockStrategy: MockStrategy = options?.mock ?? \"none\"\n  const maxConcurrency = options?.maxConcurrency ?? 10\n\n  const tasks = serverItems.map(\n    (serverItem) => () =>\n      processItem(\n        httpClient,\n        serverItem,\n        fn,\n        testRunId,\n        mockStrategy,\n        options?.environment,\n      ),\n  )\n  const resultItems = await mapWithConcurrency(tasks, maxConcurrency)\n\n  await flushTraces()\n\n  let serverTraceIds: Record<string, string> = {}\n  try {\n    const completeResult = await httpClient.completeReplay(testRunId)\n    serverTraceIds = completeResult.traceIds ?? {}\n  } catch (e) {\n    try {\n      console.error(\"Bitfab: Failed to complete replay:\", e)\n    } catch {\n      // Never crash the host app\n    }\n  }\n\n  for (const item of resultItems) {\n    if (item.traceId) {\n      item.traceId = serverTraceIds[item.traceId] ?? null\n    }\n  }\n\n  return {\n    items: resultItems,\n    testRunId,\n    testRunUrl: `${serviceUrl}${testRunUrl}`,\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "description": "Bitfab client for provider-based API calls with local BAML execution",
   "type": "module",
   "main": "./dist/index.cjs",

package/dist/chunk-BVFST7Q3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/version.generated.ts","../src/constants.ts","../src/errors.ts","../src/http.ts","../src/asyncStorage.ts","../src/replayContext.ts","../src/serialize.ts"],"sourcesContent":["/**\n * Auto-generated version file.\n * This file is generated by scripts/generate-version.ts during build.\n * DO NOT EDIT MANUALLY.\n */\n\n/**\n * SDK version from package.json (injected at build time)\n */\nexport const __version__ = \"0.13.5\"\n","/**\n * Constants for the Bitfab SDK.\n */\n\n/**\n * Default service URL for Bitfab API.\n */\nexport const DEFAULT_SERVICE_URL = \"https://bitfab.ai\"\n\n/**\n * SDK version from package.json (injected at build time)\n *\n * The version is generated at build time by scripts/generate-version.ts\n * to ensure compatibility with both Node.js and browser environments.\n */\nexport { __version__ } from \"./version.generated.js\"\n","/**\n * Shared error type for Bitfab SDK runtime errors. Lives in its own\n * module to avoid import cycles between `http.ts` and modules that need\n * to throw structured errors (e.g. `dbSnapshot.ts` validation).\n */\n\nexport class BitfabError extends Error {\n  constructor(\n    message: string,\n    public readonly url?: string,\n  ) {\n    super(message)\n    this.name = \"BitfabError\"\n  }\n}\n","/**\n * HTTP client utilities for Bitfab API requests.\n *\n * This module provides:\n * - HttpClient class for making API requests\n * - awaitOnExit helper for fire-and-forget operations that must complete before process exit\n */\n\nimport { __version__ } from \"./constants.js\"\nimport type { DbSnapshotRef } from \"./dbSnapshot.js\"\nimport { BitfabError } from \"./errors.js\"\nimport type { DbBranchLease } from \"./replayContext.js\"\n\n// BitfabError lives in `errors.ts` to break the http ↔ dbSnapshot import\n// cycle. Re-exported here for backwards compatibility with existing\n// callers that import it from \"./http.js\".\nexport { BitfabError }\n\n// Global set to track pending trace creation promises\n// This prevents promises from being garbage collected before they complete\nconst pendingTracePromises = new Set<Promise<unknown>>()\n\n/**\n * Track a promise to prevent it from being garbage collected.\n * The promise will be removed from tracking when it completes (success or failure).\n * Useful for fire-and-forget operations that need to complete before process exit.\n *\n * @param promise - The promise to track\n * @returns The same promise (for chaining)\n */\nexport function awaitOnExit<T>(promise: Promise<T>): Promise<T> {\n  pendingTracePromises.add(promise)\n  // Use void to prevent unhandled rejection warnings from the .finally() chain\n  // The actual error handling is done by the caller's .catch() on the returned promise\n  void promise\n    .finally(() => {\n      pendingTracePromises.delete(promise)\n    })\n    .catch(() => {\n      // Swallow rejection in this chain - the caller handles errors via their own .catch()\n    })\n  return promise\n}\n\n/**\n * Wait for all pending fire-and-forget operations (spans, traces) to complete.\n * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.\n *\n * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)\n */\nexport async function flushTraces(timeoutMs: number = 5000): Promise<void> {\n  if (pendingTracePromises.size === 0) {\n    return\n  }\n  await Promise.race([\n    Promise.allSettled(Array.from(pendingTracePromises)),\n    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),\n  ])\n}\n\n// Register beforeExit handler to wait for pending traces (Node.js only)\n// This ensures traces are sent before the process exits (for scripts)\nif (\n  typeof process !== \"undefined\" &&\n  process.versions != null &&\n  process.versions.node != null\n) {\n  let isFlushing = false\n  process.on(\"beforeExit\", () => {\n    if (pendingTracePromises.size > 0 && !isFlushing) {\n      isFlushing = true\n      // Wait for all pending traces to complete\n      // This keeps the event loop alive until promises resolve\n      Promise.allSettled(\n        Array.from(pendingTracePromises).map((p) =>\n          p.catch(() => {\n            // Silently ignore individual trace failures\n          }),\n        ),\n      )\n        .then(() => {\n          isFlushing = false\n        })\n        .catch(() => {\n          isFlushing = false\n        })\n    }\n  })\n}\n\nexport interface HttpClientConfig {\n  apiKey?: string\n  serviceUrl: string\n  timeout?: number\n}\n\n/**\n * HTTP client for Bitfab API requests.\n *\n * Provides methods for different API endpoints with proper error handling,\n * timeouts, and authentication.\n */\nexport class HttpClient {\n  private readonly apiKey: string | undefined\n  private readonly serviceUrl: string\n  private readonly timeout: number\n\n  constructor(config: HttpClientConfig) {\n    this.apiKey = config.apiKey\n    this.serviceUrl = config.serviceUrl\n    this.timeout = config.timeout ?? 120000\n  }\n\n  /**\n   * Make an HTTP request to the Bitfab API. Defaults to POST; pass\n   * `options.method` to use a different verb (e.g. \"PATCH\").\n   *\n   * @param endpoint - The API endpoint (without base URL)\n   * @param payload - The request body\n   * @param options - Optional request options\n   * @returns The parsed JSON response\n   * @throws {BitfabError} If the request fails\n   */\n  async request<T>(\n    endpoint: string,\n    payload: Record<string, unknown>,\n    options?: { timeout?: number; method?: \"POST\" | \"PATCH\" | \"PUT\" },\n  ): Promise<T> {\n    const url = `${this.serviceUrl}${endpoint}`\n    const timeout = options?.timeout ?? this.timeout\n    const method = options?.method ?? \"POST\"\n\n    const controller = new AbortController()\n    const timeoutId = setTimeout(() => controller.abort(), timeout)\n\n    // Serialize payload, handling circular references\n    let body: string\n    let serializationError: string | undefined\n    try {\n      body = JSON.stringify(payload)\n    } catch (error) {\n      serializationError =\n        error instanceof Error ? error.message : String(error)\n      // Create fallback payload with error info\n      body = JSON.stringify({\n        ...Object.fromEntries(\n          Object.entries(payload).filter(\n            ([, v]) => typeof v === \"string\" || typeof v === \"number\",\n          ),\n        ),\n        rawSpan: {},\n        errors: [{ step: \"json_serialize\", error: serializationError }],\n      })\n    }\n\n    try {\n      const response = await fetch(url, {\n        method,\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization: `Bearer ${this.apiKey}`,\n        },\n        body,\n        signal: controller.signal,\n      })\n\n      if (!response.ok) {\n        const errorText = await response.text()\n        throw new BitfabError(\n          `HTTP ${response.status}: ${errorText.slice(0, 500)}`,\n        )\n      }\n\n      const result = await response.json()\n\n      // Check for errors in the response\n      if (result.error) {\n        if (result.url) {\n          throw new BitfabError(\n            `${result.error} Configure it at: ${this.serviceUrl}${result.url}`,\n            result.url,\n          )\n        }\n        throw new BitfabError(result.error)\n      }\n\n      return result as T\n    } catch (error) {\n      if (error instanceof BitfabError) {\n        throw error\n      }\n      if (error instanceof Error) {\n        if (error.name === \"AbortError\") {\n          throw new BitfabError(`Request timed out after ${timeout}ms`)\n        }\n        throw new BitfabError(error.message)\n      }\n      throw new BitfabError(\"Unknown error occurred\")\n    } finally {\n      clearTimeout(timeoutId)\n    }\n  }\n\n  /**\n   * Look up a function by name.\n   * Blocks until complete - needed for function execution.\n   */\n  async lookupFunction<T>(name: string): Promise<T> {\n    return this.request<T>(\"/api/sdk/functions/lookup\", { name })\n  }\n\n  /**\n   * Send an internal trace (from BAML execution).\n   * Fire-and-forget with awaitOnExit - doesn't block the caller.\n   */\n  sendInternalTrace(\n    functionId: string,\n    payload: Record<string, unknown>,\n  ): void {\n    void awaitOnExit(\n      this.request(`/api/sdk/functions/${functionId}/traces`, {\n        ...payload,\n        sdkVersion: __version__,\n      }),\n    ).catch((error) => {\n      try {\n        console.error(\"Bitfab: Failed to create trace:\", error)\n      } catch {}\n    })\n  }\n\n  /**\n   * Send an external span (from withSpan wrapper or OpenAI tracing).\n   * Fire-and-forget with awaitOnExit - doesn't block the caller.\n   * Returns the tracked promise so callers can optionally await it.\n   */\n  sendExternalSpan(payload: Record<string, unknown>): Promise<unknown> {\n    return awaitOnExit(\n      this.request(\"/api/sdk/externalSpans\", {\n        ...payload,\n        sdkVersion: __version__,\n      }),\n    ).catch((error) => {\n      try {\n        console.error(\"Bitfab: Failed to create external span:\", error)\n      } catch {}\n    })\n  }\n\n  /**\n   * Send an external trace (from OpenAI tracing).\n   * Fire-and-forget with awaitOnExit - doesn't block the caller.\n   */\n  sendExternalTrace(payload: Record<string, unknown>): void {\n    void awaitOnExit(\n      this.request(\"/api/sdk/externalTraces\", {\n        ...payload,\n        sdkVersion: __version__,\n      }),\n    ).catch((error) => {\n      try {\n        console.error(\"Bitfab: Failed to create external trace:\", error)\n      } catch {}\n    })\n  }\n\n  /**\n   * Partial update of an existing external trace identified by sourceTraceId.\n   * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;\n   * returns a tracked promise that callers may optionally await.\n   */\n  patchTrace(\n    sourceTraceId: string,\n    payload: {\n      appendContexts?: Record<string, unknown>[]\n      mergeMetadata?: Record<string, unknown>\n      setSessionId?: string\n    },\n  ): Promise<unknown> {\n    const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`\n    return awaitOnExit(\n      this.request(endpoint, payload, { method: \"PATCH\" }),\n    ).catch((error) => {\n      try {\n        console.error(\"Bitfab: Failed to patch trace:\", error)\n      } catch {}\n    })\n  }\n\n  /**\n   * Start a replay session by fetching historical traces.\n   * Blocking call — creates a test run and returns lightweight item references.\n   */\n  async startReplay(\n    traceFunctionKey: string,\n    limit: number,\n    traceIds?: string[],\n    codeChangeDescription?: string,\n    codeChangeFiles?: CodeChangeFile[],\n    includeDbBranchLease?: boolean,\n  ): Promise<StartReplayResponse> {\n    const payload: Record<string, unknown> = { traceFunctionKey, limit }\n    if (traceIds) {\n      payload.traceIds = traceIds\n    }\n    if (codeChangeDescription !== undefined) {\n      payload.codeChangeDescription = codeChangeDescription\n    }\n    if (codeChangeFiles !== undefined) {\n      payload.codeChangeFiles = codeChangeFiles\n    }\n    if (includeDbBranchLease) {\n      payload.includeDbBranchLease = true\n    }\n    // When DB branching is on, the server resolves a Neon preview branch\n    // per item (snapshot + restore + poll), which can run ~5-10s each.\n    // Use a generous timeout to cover the worst case; otherwise the SDK\n    // would time out before a healthy server finished.\n    const timeout = includeDbBranchLease ? 180_000 : 30_000\n    return this.request<StartReplayResponse>(\"/api/sdk/replay/start\", payload, {\n      timeout,\n    })\n  }\n\n  /**\n   * Fetch an external span by ID.\n   * Blocking GET request.\n   */\n  async getExternalSpan(spanId: string): Promise<ExternalSpanResponse> {\n    const url = `${this.serviceUrl}/api/sdk/externalSpans/${spanId}`\n    const controller = new AbortController()\n    const timeoutId = setTimeout(() => controller.abort(), 30_000)\n\n    try {\n      const response = await fetch(url, {\n        method: \"GET\",\n        headers: { Authorization: `Bearer ${this.apiKey}` },\n        signal: controller.signal,\n      })\n\n      if (!response.ok) {\n        const errorText = await response.text()\n        throw new BitfabError(\n          `HTTP ${response.status}: ${errorText.slice(0, 500)}`,\n        )\n      }\n\n      return (await response.json()) as ExternalSpanResponse\n    } catch (error) {\n      if (error instanceof BitfabError) {\n        throw error\n      }\n      if (error instanceof Error) {\n        if (error.name === \"AbortError\") {\n          throw new BitfabError(\"Request timed out after 30000ms\")\n        }\n        throw new BitfabError(error.message)\n      }\n      throw new BitfabError(\"Unknown error occurred\")\n    } finally {\n      clearTimeout(timeoutId)\n    }\n  }\n\n  /**\n   * Fetch the span tree for a root span.\n   * Blocking GET request.\n   */\n  async getSpanTree(externalSpanId: string): Promise<SpanTreeResponse> {\n    const url = `${this.serviceUrl}/api/sdk/replay/spanTree/${externalSpanId}`\n    const controller = new AbortController()\n    const timeoutId = setTimeout(() => controller.abort(), 30_000)\n\n    try {\n      const response = await fetch(url, {\n        method: \"GET\",\n        headers: { Authorization: `Bearer ${this.apiKey}` },\n        signal: controller.signal,\n      })\n\n      if (!response.ok) {\n        const errorText = await response.text()\n        throw new BitfabError(\n          `HTTP ${response.status}: ${errorText.slice(0, 500)}`,\n        )\n      }\n\n      return (await response.json()) as SpanTreeResponse\n    } catch (error) {\n      if (error instanceof BitfabError) {\n        throw error\n      }\n      if (error instanceof Error) {\n        if (error.name === \"AbortError\") {\n          throw new BitfabError(\"Request timed out after 30000ms\")\n        }\n        throw new BitfabError(error.message)\n      }\n      throw new BitfabError(\"Unknown error occurred\")\n    } finally {\n      clearTimeout(timeoutId)\n    }\n  }\n\n  /**\n   * Mark a replay test run as completed.\n   * Blocking call.\n   */\n  async completeReplay(testRunId: string): Promise<CompleteReplayResponse> {\n    return this.request<CompleteReplayResponse>(\n      \"/api/sdk/replay/complete\",\n      { testRunId },\n      { timeout: 30_000 },\n    )\n  }\n\n  /**\n   * Ask the server to materialize a per-trace DB branch lease from a\n   * captured `dbSnapshotRef`. Blocking — the resolver creates a Neon\n   * snapshot + preview branch and polls operations to readiness, which\n   * can take seconds.\n   */\n  async resolveDbBranchLease(\n    testRunId: string,\n    traceId: string,\n    dbSnapshotRef: DbSnapshotRef,\n  ): Promise<{ lease: DbBranchLease }> {\n    return this.request<{ lease: DbBranchLease }>(\n      \"/api/sdk/replay/resolveDbBranchLease\",\n      { testRunId, traceId, dbSnapshotRef },\n      { timeout: 90_000 },\n    )\n  }\n\n  /** Release a previously-resolved DB branch lease. Idempotent server-side. */\n  async releaseDbBranchLease(leaseId: string): Promise<void> {\n    await this.request<{ released: true }>(\n      \"/api/sdk/replay/releaseDbBranchLease\",\n      { leaseId },\n      { timeout: 30_000 },\n    )\n  }\n}\n\nexport interface TokenUsage {\n  input: number | null\n  output: number | null\n  cached: number | null\n  total: number | null\n}\n\n/**\n * Describes a single file edited as part of a code change.\n *\n * - `path`: file path (relative to the repo root, or any consistent root)\n * - `before`: file contents before the change (\"\" for newly created files)\n * - `after`: file contents after the change (\"\" for deleted files)\n */\nexport interface CodeChangeFile {\n  path: string\n  before: string\n  after: string\n}\n\nexport interface StartReplayResponse {\n  testRunId: string\n  testRunUrl: string\n  items: Array<{\n    traceId: string\n    externalSpanId: string\n    durationMs: number | null\n    tokens: TokenUsage | null\n    model: string | null\n    /**\n     * The DB snapshot ref captured by the SDK at trace open. Surfaced so\n     * the SDK can pass it to the lease-resolver step (or report when no\n     * snapshot was captured for this trace).\n     */\n    dbSnapshotRef?: DbSnapshotRef\n    /**\n     * Populated once the server-side resolver has materialized a per-item\n     * branch from `dbSnapshotRef`. The SDK exposes this to customer code\n     * via `ReplayEnvironment`. Absent until the resolver lands.\n     */\n    dbBranchLease?: DbBranchLease\n  }>\n}\n\nexport interface ExternalSpanResponse {\n  id: string\n  externalTraceId: string\n  rawData: {\n    span_data: {\n      input: unknown\n      output: unknown\n      input_meta?: unknown\n      output_meta?: unknown\n      input_serialized?: { json: unknown; meta: unknown }\n      output_serialized?: { json: unknown; meta: unknown }\n    }\n  }\n}\n\nexport interface CompleteReplayResponse {\n  id: string\n  status: string\n  traceIds?: Record<string, string>\n}\n\nexport interface SpanTreeNode {\n  sourceSpanId: string\n  traceFunctionKey: string\n  spanName: string\n  type: string\n  output: unknown\n  outputMeta?: unknown\n  children: SpanTreeNode[]\n}\n\nexport interface SpanTreeResponse {\n  root: SpanTreeNode\n}\n","/**\n * Shared AsyncLocalStorage loader.\n *\n * Provides two ways to initialize AsyncLocalStorage:\n *\n * 1. **Synchronous registration** (preferred for Node.js):\n *    `asyncStorageNode.ts` calls `registerAsyncLocalStorageClass()` at module\n *    evaluation time, so the class is available immediately — no async gap.\n *    The `node.ts` entry point imports it before anything else.\n *\n * 2. **Async dynamic import** (fallback for the default entry point):\n *    Loads `node:async_hooks` via a bundler-safe dynamic import. This is used\n *    by the default `index.ts` entry point so the SDK works in browsers\n *    (where the import silently fails) and in Node.js when imported via the\n *    default entry point.\n *\n * ## Why the dynamic import looks like this\n *\n * We need to handle three environments:\n *\n * 1. **Pure Node.js** — `import(\"node:async_hooks\")` works natively.\n * 2. **Webpack/Turbopack (Next.js server)** — The bundler processes\n *    `import()` calls at build time. The `webpackIgnore` magic comment tells\n *    webpack (and turbopack) to emit a native `import()` call instead of\n *    trying to resolve it, so Node.js handles it at runtime.\n * 3. **Browsers / Edge** — The `process.versions?.node` guard prevents\n *    execution entirely. If it somehow runs, `.catch(() => {})` swallows\n *    the failure.\n */\n\nexport interface AsyncLocalStorageLike<T> {\n  getStore(): T | undefined\n  run<R>(store: T, fn: () => R): R\n}\n\nlet AsyncLocalStorageClass: (new () => AsyncLocalStorageLike<unknown>) | null =\n  null\nlet initDone = false\n\n/**\n * Register the AsyncLocalStorage class synchronously.\n *\n * Called by `asyncStorageNode.ts` at module evaluation time so the class\n * is available before any span is created — no async gap, no race condition.\n *\n * Safe to call multiple times; subsequent calls are no-ops.\n */\nexport function registerAsyncLocalStorageClass(\n  cls: new () => AsyncLocalStorageLike<unknown>,\n): void {\n  if (!AsyncLocalStorageClass) {\n    AsyncLocalStorageClass = cls\n  }\n  initDone = true\n}\n\n/**\n * Assert that AsyncLocalStorage was registered successfully.\n *\n * Called by `node.ts` after importing `asyncStorageNode.ts` to catch\n * import-order bugs at startup rather than silently degrading to the\n * browser fallback (flat spans with no nesting).\n *\n * This should ONLY be called from the Node.js entry point where we\n * know `node:async_hooks` must be available.\n */\nexport function assertAsyncStorageRegistered(): void {\n  if (!AsyncLocalStorageClass) {\n    console.warn(\n      \"Bitfab: AsyncLocalStorage not available — nested span context will not propagate.\",\n    )\n  }\n}\n\nexport const asyncStorageReady: Promise<void> = (\n  typeof process !== \"undefined\" && process.versions?.node\n    ? // The join trick hides \"node:async_hooks\" from static analysis so\n      // bundlers that ban Node.js built-ins don't fail at build time.\n      // webpackIgnore tells webpack/turbopack to emit a native import()\n      // so Node.js can resolve the module at runtime.\n      import(\n        /* webpackIgnore: true */\n        [\"node\", \"async_hooks\"].join(\":\")\n      )\n        .then(\n          (mod: {\n            AsyncLocalStorage: new () => AsyncLocalStorageLike<unknown>\n          }) => {\n            registerAsyncLocalStorageClass(mod.AsyncLocalStorage)\n          },\n        )\n        .catch(() => {})\n    : Promise.resolve()\n).then(() => {\n  initDone = true\n})\n\nexport function isAsyncStorageInitDone(): boolean {\n  return initDone\n}\n\nexport function createAsyncLocalStorage<T>(): AsyncLocalStorageLike<T> | null {\n  return AsyncLocalStorageClass\n    ? (new AsyncLocalStorageClass() as AsyncLocalStorageLike<T>)\n    : null\n}\n","/**\n * Replay context propagation via AsyncLocalStorage.\n *\n * When set, the withSpan wrapper injects testRunId into the span payload\n * so that new spans created during replay are linked to the test run.\n * Optionally carries a mock tree so child spans can return historical\n * outputs instead of executing.\n */\n\nimport {\n  type AsyncLocalStorageLike,\n  asyncStorageReady,\n  createAsyncLocalStorage,\n} from \"./asyncStorage.js\"\n\n/** A single span entry in the mock tree with its historical output. */\nexport interface MockSpan {\n  sourceSpanId: string\n  output: unknown\n  outputMeta?: unknown\n}\n\n/**\n * Per-item DB branch lease resolved by the Bitfab service from the source\n * trace's `dbSnapshotRef`. Carried on the replay context so that\n * `bitfab.db.url()` can return the branch URL transparently, and so the\n * process-isolated replay runner can materialize it into a `.env` overlay\n * file before customer code initializes its DB client.\n */\nexport interface DbBranchLease {\n  leaseId: string\n  /** Env var name the customer's app reads, e.g. \"DATABASE_URL\". */\n  envKey: string\n  databaseUrl: string\n  expiresAt: string\n  providerConsoleUrl?: string\n  readOnly?: boolean\n  /**\n   * How the resolver pinned the snapshot.\n   * - \"timestamp\": Neon snapshot at the SDK's wall-clock; bounded by\n   *   replication lag at that moment.\n   * - \"lsn\": customer-LSN mapped to a replica snapshot (future; Ardent\n   *   mapping required).\n   */\n  precision: \"timestamp\" | \"lsn\"\n}\n\n/**\n * Pre-built lookup table of historical span outputs.\n * Keys are `${traceFunctionKey}:${spanName}:${callIndex}` so that repeated\n * calls with the same (key, name) are matched by call order, but spans\n * sharing only the traceFunctionKey (different name) do not collide.\n */\nexport interface MockTree {\n  spans: Map<string, MockSpan>\n}\n\nexport interface ReplayContext {\n  testRunId: string\n  traceId?: string\n  inputSourceSpanId?: string\n  /**\n   * External trace ID from `external_traces.id`. Used for span-chain\n   * lookup against the source platform's trace tree (Braintrust, etc.).\n   * NOT the same as the Bitfab `traceId` — see `sourceBitfabTraceId`.\n   */\n  inputSourceTraceId?: string\n  /**\n   * The Bitfab `traces.id` of the historical trace that produced this\n   * replay item's input. This is what customer-facing surfaces (e.g.\n   * `ReplayEnvironment.traceId`) should expose, since it's the ID the\n   * customer sees in the Bitfab dashboard.\n   */\n  sourceBitfabTraceId?: string\n  mockTree?: MockTree\n  callCounters?: Map<string, number>\n  mockStrategy?: \"none\" | \"all\" | \"marked\"\n  dbBranchLease?: DbBranchLease\n}\n\nlet replayContextStorage: AsyncLocalStorageLike<ReplayContext | null> | null =\n  null\n\nexport const replayContextReady: Promise<void> = asyncStorageReady.then(() => {\n  replayContextStorage = createAsyncLocalStorage<ReplayContext | null>()\n})\n\n/** Get the current replay context, if any. */\nexport function getReplayContext(): ReplayContext | null {\n  return replayContextStorage?.getStore() ?? null\n}\n\n/** Run a function within a replay context. */\nexport function runWithReplayContext<T>(ctx: ReplayContext, fn: () => T): T {\n  if (replayContextStorage) {\n    return replayContextStorage.run(ctx, fn)\n  }\n  return fn()\n}\n","/**\n * Serialization utilities for Bitfab SDK.\n *\n * This module provides serialization with type metadata preservation,\n * using superjson for handling special JavaScript types like Date, Map,\n * Set, BigInt, undefined, etc.\n */\n\nimport superjson from \"superjson\"\n\n/**\n * Serialized value with JSON data and optional superjson meta for type preservation.\n *\n * The json field contains the JSON-serializable data.\n * The meta field (if present) contains superjson type information for deserializing\n * special types like Date, Map, Set, BigInt, etc.\n */\nexport interface SerializedValue {\n  json: unknown\n  meta?: unknown\n}\n\n// Cap on serialized payload size. superjson can succeed on values like SDK\n// client instances (OpenAI, etc.) and produce hundreds of KB to MB of useless\n// internal state. Anything beyond this is replaced with a stub so the span\n// still ships and the trace isn't dropped server-side.\nconst MAX_SERIALIZED_BYTES = 512_000\n\nfunction describeValue(value: unknown): string {\n  try {\n    const ctorName = (value as { constructor?: { name?: string } })?.constructor\n      ?.name\n    if (ctorName && ctorName !== \"Object\") {\n      return ctorName\n    }\n  } catch {\n    // Property access on `value` can throw (Proxy, poisoned getter).\n  }\n  return typeof value\n}\n\nfunction unserializableStub(value: unknown, reason: string): SerializedValue {\n  let summary: string\n  try {\n    summary = `<unserializable: ${describeValue(value)} (${reason})>`\n  } catch {\n    summary = `<unserializable (${reason})>`\n  }\n  return { json: summary }\n}\n\n/**\n * Serialize a value using superjson for trace storage.\n *\n * Handles arbitrary JavaScript values including:\n * - Date, RegExp, Error\n * - Map, Set\n * - BigInt\n * - undefined (in objects/arrays)\n * - Circular references\n *\n * Guarantees:\n * - Never throws. Pathological inputs (SDK clients, proxies, poisoned\n *   getters, circular graphs that defeat superjson) return a stub string.\n * - Never returns a payload larger than MAX_SERIALIZED_BYTES; oversized\n *   inputs are replaced with a stub. Without this the wire-side\n *   `JSON.stringify` in http.ts can produce a request that times out or\n *   gets rejected, leaving a trace with zero spans.\n *\n * @param value - Any JavaScript value to serialize\n * @returns SerializedValue with 'json' field containing the data.\n *          If type metadata is needed for reconstruction, includes 'meta' field.\n *\n * @example\n * ```typescript\n * const result = serializeValue(new Date('2024-01-15T10:30:00Z'))\n * // result.json contains the ISO string\n * // result.meta contains type info for Date reconstruction\n * ```\n */\nexport function serializeValue(value: unknown): SerializedValue {\n  try {\n    const { json, meta } = superjson.serialize(value)\n\n    let size: number\n    try {\n      size = JSON.stringify(json).length\n    } catch {\n      return unserializableStub(value, \"stringify_failed_after_superjson\")\n    }\n    if (size > MAX_SERIALIZED_BYTES) {\n      return unserializableStub(value, `too_large_${size}_bytes`)\n    }\n\n    return meta ? { json, meta } : { json }\n  } catch {\n    try {\n      return { json: JSON.parse(JSON.stringify(value)) }\n    } catch {\n      return unserializableStub(value, \"json_stringify_failed\")\n    }\n  }\n}\n\n/**\n * Deserialize a value that was serialized with serializeValue.\n *\n * @param serialized - A SerializedValue object with 'json' and optional 'meta'\n * @returns The reconstructed JavaScript value\n *\n * @example\n * ```typescript\n * const serialized = serializeValue(new Date('2024-01-15'))\n * const date = deserializeValue(serialized)\n * // date is a Date object\n * ```\n */\nexport function deserializeValue(serialized: SerializedValue): unknown {\n  if (serialized.meta === undefined) {\n    // No metadata, return as-is\n    return serialized.json\n  }\n\n  // Use superjson to deserialize with type reconstruction\n  // Cast json to the expected superjson type\n  type SuperJSONResult = Parameters<typeof superjson.deserialize>[0]\n  return superjson.deserialize({\n    json: serialized.json as SuperJSONResult[\"json\"],\n    meta: serialized.meta as SuperJSONResult[\"meta\"],\n  })\n}\n"],"mappings":"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","names":[]}

package/dist/replay-CLQKO7U7.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/replay.ts"],"sourcesContent":["/**\n * Replay historical traces through a function and create a test run.\n *\n * The replay flow has three phases:\n * 1. Start — fetches historical traces from the server and creates a test run\n * 2. Execute — re-runs each trace's inputs through the provided function locally\n * 3. Complete — marks the test run as completed on the server\n */\n\nimport type { DbSnapshotRef } from \"./dbSnapshot.js\"\nimport type {\n  CodeChangeFile,\n  HttpClient,\n  SpanTreeNode,\n  TokenUsage,\n} from \"./http.js\"\nimport { flushTraces } from \"./http.js\"\nimport type { DbBranchLease, MockTree } from \"./replayContext.js\"\nimport { replayContextReady, runWithReplayContext } from \"./replayContext.js\"\nimport type { ReplayEnvironment } from \"./replayEnvironment.js\"\nimport { deserializeValue } from \"./serialize.js\"\n\nexport type MockStrategy = \"none\" | \"all\" | \"marked\"\n\nexport interface ReplayOptions {\n  /** Maximum number of traces to replay (1–100, default 5). */\n  limit?: number\n  /** Optional list of specific trace IDs to replay. */\n  traceIds?: string[]\n  /** Maximum number of items to process in parallel. Set to 1 for sequential. Default 10. */\n  maxConcurrency?: number\n  /**\n   * Description of the code change being tested in this replay. Stored on\n   * the resulting experiment so the change can be reviewed alongside results.\n   */\n  codeChangeDescription?: string\n  /**\n   * Files edited as part of this code change. Each entry holds the file path\n   * and the full `before`/`after` contents — the agent reads each file before\n   * and after editing and passes the two strings. Use `\"\"` for newly created\n   * files (`before`) or deleted files (`after`).\n   */\n  codeChangeFiles?: CodeChangeFile[]\n  /**\n   * Mock strategy for child spans during replay.\n   * - \"none\": everything runs real code (default)\n   * - \"all\": every child withSpan returns historical output\n   * - \"marked\": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked\n   */\n  mock?: MockStrategy\n  /**\n   * Per-trace environment. When the source trace carries a DB branching\n   * snapshot, the SDK populates `environment.databaseUrl` before invoking\n   * `fn` for that item and resets it after. Customer code reads from the\n   * environment to pick up the per-trace branch URL.\n   */\n  environment?: ReplayEnvironment\n}\n\nexport interface ReplayItem<T> {\n  /** Trace ID of the new trace created during replay. */\n  traceId: string | null\n  /** Deserialized inputs from the original trace. */\n  input: unknown[]\n  /** The result returned by the function during replay, or undefined on error. */\n  result: T | undefined\n  /** The original output from the historical trace. */\n  originalOutput: unknown\n  /** Error message if the function threw, or null on success. */\n  error: string | null\n  /** Original trace duration in milliseconds, or null if timestamps are missing. */\n  durationMs: number | null\n  /** Token usage from the original trace, or null if not captured. */\n  tokens: TokenUsage | null\n  /** Model name from the original trace, or null if not captured. */\n  model: string | null\n  /**\n   * The DB snapshot ref the SDK captured at trace open. Useful for debugging\n   * (\"what state was this trace pinned to?\") and for customers building\n   * their own resolvers. Undefined when the source trace was captured\n   * without `dbSnapshot` configured.\n   */\n  dbSnapshotRef: DbSnapshotRef | null\n}\n\nexport type { CodeChangeFile, TokenUsage }\n\nexport interface ReplayResult<T> {\n  /** Individual replay items with inputs, results, and comparison data. */\n  items: ReplayItem<T>[]\n  /** The test run ID created on the server. */\n  testRunId: string\n  /** Full URL to view the test run in the dashboard. */\n  testRunUrl: string\n}\n\n/**\n * Deserialize inputs from a historical span's rawData.\n *\n * Prefers superjson-serialized `input_meta` for type preservation,\n * falls back to the raw `input` field.\n */\nfunction deserializeInputs(spanData: Record<string, unknown>): unknown[] {\n  const inputMeta = spanData.input_meta as unknown\n  const rawInput = spanData.input\n\n  // If superjson meta is available, deserialize with type reconstruction\n  if (inputMeta !== undefined && inputMeta !== null) {\n    const deserialized = deserializeValue({ json: rawInput, meta: inputMeta })\n    if (Array.isArray(deserialized)) {\n      return deserialized\n    }\n    return deserialized !== undefined && deserialized !== null\n      ? [deserialized]\n      : []\n  }\n\n  // Fall back to raw input\n  if (Array.isArray(rawInput)) {\n    return rawInput\n  }\n  return rawInput !== undefined && rawInput !== null ? [rawInput] : []\n}\n\n/**\n * Deserialize the original output from a historical span's rawData.\n */\nfunction deserializeOutput(spanData: Record<string, unknown>): unknown {\n  const outputMeta = spanData.output_meta as unknown\n  const rawOutput = spanData.output\n\n  if (outputMeta !== undefined && outputMeta !== null) {\n    return deserializeValue({ json: rawOutput, meta: outputMeta })\n  }\n\n  return rawOutput\n}\n\n/**\n * Walk the children of a root span tree node in depth-first order and build\n * a MockTree keyed by `${traceFunctionKey}:${spanName}:${callIndex}`.\n *\n * The historical root itself is NOT walked. At replay time the runtime root\n * span has `isRootSpan === true` and never queries the mockTree (mock\n * interception is skipped for root spans by design), so the root has nothing\n * to look up. Walking it would just leave an unreachable entry in the table.\n *\n * The (key, name) compound match is what disambiguates same-key spans:\n *   - A wrapped function's children commonly share its traceFunctionKey via\n *     the fluent `getFunction(key).withSpan({ name }, ...)` pattern. They\n *     disambiguate by `name`, never colliding with each other.\n *   - Recursion: same (key, name) at every depth. callIndex per (key, name)\n *     orders them correctly without leaking the historical root into the\n *     nested call's slot.\n *   - Outer-wrapper replay scripts: the outer wrapper's `name` is distinct\n *     from anything in the historical tree (it only exists at replay), so\n *     its presence never disturbs counters or lookups for spans that do\n *     exist in the historical tree.\n */\nfunction buildMockTree(rootNode: SpanTreeNode): MockTree {\n  const spans = new Map<\n    string,\n    { sourceSpanId: string; output: unknown; outputMeta?: unknown }\n  >()\n  const counters = new Map<string, number>()\n\n  function walk(node: SpanTreeNode): void {\n    const key = node.traceFunctionKey\n    if (key) {\n      const name = node.spanName\n      const counterKey = `${key}:${name}`\n      const index = counters.get(counterKey) ?? 0\n      counters.set(counterKey, index + 1)\n      spans.set(`${counterKey}:${index}`, {\n        sourceSpanId: node.sourceSpanId,\n        output: node.output,\n        outputMeta: node.outputMeta,\n      })\n    }\n    for (const child of node.children) {\n      walk(child)\n    }\n  }\n\n  for (const child of rootNode.children) {\n    walk(child)\n  }\n\n  return { spans }\n}\n\n/**\n * Execute a single replay item: fetch span data, deserialize inputs, call\n * the function within a replay context that injects testRunId into new spans.\n */\nasync function processItem<TReturn>(\n  httpClient: HttpClient,\n  serverItem: {\n    traceId: string\n    externalSpanId: string\n    durationMs: number | null\n    tokens: TokenUsage | null\n    model: string | null\n    dbSnapshotRef?: DbSnapshotRef\n    dbBranchLease?: DbBranchLease\n  },\n  // biome-ignore lint/suspicious/noExplicitAny: replay deserializes inputs from historical data\n  fn: (...args: any[]) => TReturn | Promise<TReturn>,\n  testRunId: string,\n  mockStrategy: MockStrategy,\n  environment: ReplayEnvironment | undefined,\n): Promise<ReplayItem<TReturn>> {\n  // The server-side resolver materializes a Neon preview branch per item\n  // during `/api/sdk/replay/start` (when the customer passed `environment`,\n  // which triggers `includeDbBranchLease: true`). The lease arrives on the\n  // server item; we just attach it to the replay context and release the\n  // branch in `finally` so any throw — in fetch, mock-tree build, or the\n  // customer fn — frees the Neon resource. Items whose source trace had\n  // no snapshot ref, or whose resolve failed server-side, arrive without\n  // a lease; `env.active` will be `false` for those.\n  const lease = environment ? serverItem.dbBranchLease : undefined\n\n  let inputs: unknown[] = []\n  let originalOutput: unknown\n  let result: TReturn | undefined\n  let error: string | null = null\n  const replayedTraceId = crypto.randomUUID()\n\n  try {\n    const span = await httpClient.getExternalSpan(serverItem.externalSpanId)\n    const spanData = (span.rawData?.span_data ?? {}) as Record<string, unknown>\n\n    inputs = deserializeInputs(spanData)\n    originalOutput = deserializeOutput(spanData)\n\n    // Build mock tree when mocking is active\n    let mockTree: MockTree | undefined\n    if (mockStrategy === \"all\" || mockStrategy === \"marked\") {\n      const treeResponse = await httpClient.getSpanTree(\n        serverItem.externalSpanId,\n      )\n      mockTree = buildMockTree(treeResponse.root)\n    }\n\n    const maybePromise = runWithReplayContext(\n      {\n        testRunId,\n        traceId: replayedTraceId,\n        inputSourceSpanId: span.id,\n        inputSourceTraceId: span.externalTraceId,\n        sourceBitfabTraceId: serverItem.traceId,\n        mockTree,\n        callCounters: mockTree ? new Map() : undefined,\n        mockStrategy,\n        dbBranchLease: lease,\n      },\n      () => fn(...inputs),\n    )\n    result = maybePromise instanceof Promise ? await maybePromise : maybePromise\n  } catch (e) {\n    error = e instanceof Error ? e.message : String(e)\n  } finally {\n    if (lease) {\n      try {\n        await httpClient.releaseDbBranchLease(lease.leaseId)\n      } catch (e) {\n        try {\n          console.warn(\n            `Bitfab: failed to release DB branch lease ${lease.leaseId} (TTL janitor will catch it): ${\n              e instanceof Error ? e.message : String(e)\n            }`,\n          )\n        } catch {\n          // Never crash the host\n        }\n      }\n    }\n  }\n\n  return {\n    traceId: replayedTraceId,\n    input: inputs,\n    result,\n    originalOutput,\n    error,\n    durationMs: serverItem.durationMs ?? null,\n    tokens: serverItem.tokens ?? null,\n    model: serverItem.model ?? null,\n    dbSnapshotRef: serverItem.dbSnapshotRef ?? null,\n  }\n}\n\n/**\n * Run async tasks with a concurrency limit.\n * Each task factory is called when a slot opens; results preserve input order.\n */\nasync function mapWithConcurrency<T>(\n  tasks: Array<() => Promise<T>>,\n  maxConcurrency: number,\n): Promise<T[]> {\n  const results: T[] = new Array(tasks.length)\n  let nextIndex = 0\n\n  async function worker(): Promise<void> {\n    while (nextIndex < tasks.length) {\n      const index = nextIndex++\n      results[index] = await tasks[index]()\n    }\n  }\n\n  const workers = Array.from(\n    { length: Math.min(maxConcurrency, tasks.length) },\n    () => worker(),\n  )\n  await Promise.all(workers)\n  return results\n}\n\n/**\n * Replay historical traces through a function and create a test run.\n *\n * @internal Called by Bitfab.replay — not part of the public API.\n */\nexport async function replay<TReturn>(\n  httpClient: HttpClient,\n  serviceUrl: string,\n  traceFunctionKey: string,\n  // biome-ignore lint/suspicious/noExplicitAny: replay deserializes inputs from historical data\n  fn: (...args: any[]) => TReturn | Promise<TReturn>,\n  options?: ReplayOptions,\n): Promise<ReplayResult<TReturn>> {\n  await replayContextReady\n\n  const {\n    testRunId,\n    testRunUrl,\n    items: serverItems,\n  } = await httpClient.startReplay(\n    traceFunctionKey,\n    options?.limit ?? 5,\n    options?.traceIds,\n    options?.codeChangeDescription,\n    options?.codeChangeFiles,\n    options?.environment !== undefined, // includeDbBranchLease\n  )\n\n  const mockStrategy: MockStrategy = options?.mock ?? \"none\"\n  const maxConcurrency = options?.maxConcurrency ?? 10\n\n  const tasks = serverItems.map(\n    (serverItem) => () =>\n      processItem(\n        httpClient,\n        serverItem,\n        fn,\n        testRunId,\n        mockStrategy,\n        options?.environment,\n      ),\n  )\n  const resultItems = await mapWithConcurrency(tasks, maxConcurrency)\n\n  await flushTraces()\n\n  let serverTraceIds: Record<string, string> = {}\n  try {\n    const completeResult = await httpClient.completeReplay(testRunId)\n    serverTraceIds = completeResult.traceIds ?? {}\n  } catch (e) {\n    try {\n      console.error(\"Bitfab: Failed to complete replay:\", e)\n    } catch {\n      // Never crash the host app\n    }\n  }\n\n  for (const item of resultItems) {\n    if (item.traceId) {\n      item.traceId = serverTraceIds[item.traceId] ?? null\n    }\n  }\n\n  return {\n    items: resultItems,\n    testRunId,\n    testRunUrl: `${serviceUrl}${testRunUrl}`,\n  }\n}\n"],"mappings":"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","names":[]}