@bitfab/sdk 0.32.0 → 0.33.0

package/dist/index.d.cts

@@ -143,6 +143,124 @@ interface MockOverride {
     value: MockValue;
 }
 
+/**
+ * Replay context propagation via AsyncLocalStorage.
+ *
+ * When set, the withSpan wrapper injects testRunId into the span payload
+ * so that new spans created during replay are linked to the test run.
+ * Optionally carries a mock tree so child spans can return historical
+ * outputs instead of executing.
+ */
+
+/**
+ * A single span entry in the mock tree.
+ *
+ * Under the eager path (`mock: "all"`) `output`/`outputMeta` are populated
+ * inline. Under the lazy path (`marked` / overrides) they are absent and the
+ * recorded output is fetched on demand via `externalSpanId` - see
+ * {@link ReplayContext.fetchSpanOutput}.
+ */
+interface MockSpan {
+    sourceSpanId: string;
+    /** Row id accepted by `getExternalSpan`, for the lazy per-span output fetch. */
+    externalSpanId?: string;
+    output?: unknown;
+    outputMeta?: unknown;
+}
+/**
+ * Per-item DB branch resolved by the Bitfab service from the source
+ * trace's `dbSnapshotRef`. Carried on the replay context so that
+ * customer code reads `databaseUrl` through `getCurrentReplayBranch()`, and so
+ * the process-isolated replay runner can materialize it into a `.env`
+ * overlay file before customer code initializes its DB client.
+ *
+ * `neonBranchId` is the literal Neon branch id; passing it to
+ * `releaseDbBranchLease` deletes that branch.
+ */
+interface DbBranchLease {
+    neonBranchId: string;
+    /** Env var name the customer's app reads, e.g. "DATABASE_URL". */
+    envKey: string;
+    databaseUrl: string;
+    expiresAt: string;
+    /**
+     * The instant the branch was pinned to (the source trace's wall clock).
+     * Echoed back in `db_snapshot_usage` on the replayed trace's completion.
+     */
+    snapshotTimestamp?: string;
+    providerConsoleUrl?: string;
+    readOnly?: boolean;
+    /**
+     * The branch's region, e.g. `aws-us-east-1`. A compute runs in its project's
+     * region, so a runner elsewhere pays that round trip on every query.
+     */
+    region?: string;
+}
+/**
+ * Pre-built lookup table of historical span outputs.
+ * Keys are `${traceFunctionKey}:${spanName}:${callIndex}` so that repeated
+ * calls with the same (key, name) are matched by call order, but spans
+ * sharing only the traceFunctionKey (different name) do not collide.
+ */
+interface MockTree {
+    spans: Map<string, MockSpan>;
+}
+interface ReplayContext {
+    testRunId: string;
+    traceId?: string;
+    inputSourceSpanId?: string;
+    /**
+     * External trace ID from `external_traces.id`. Used for span-chain
+     * lookup against the source platform's trace tree (Braintrust, etc.).
+     * NOT the same as the Bitfab `traceId` - see `sourceBitfabTraceId`.
+     */
+    inputSourceTraceId?: string;
+    /**
+     * The Bitfab `traces.id` of the historical trace that produced this
+     * replay item's input. This is what customer-facing surfaces (e.g.
+     * `ReplayBranch.traceId`) should expose, since it's the ID the
+     * customer sees in the Bitfab dashboard.
+     */
+    sourceBitfabTraceId?: string;
+    mockTree?: MockTree;
+    callCounters?: Map<string, number>;
+    mockStrategy?: "none" | "all" | "marked";
+    /**
+     * Resolved override chain for this replay, per-call overrides first then
+     * registered ones (first matcher wins). Empty/absent when no overrides apply.
+     */
+    mockOverrides?: MockOverride[];
+    /**
+     * Memoized lazy fetch of a span's recorded output (deserialized), keyed by
+     * `externalSpanId`. Present ONLY on the lazy path (`marked` / overrides);
+     * absent under `mock: "all"`, where outputs are inline on the mock tree. Its
+     * presence is the signal that outputs must be fetched rather than read inline.
+     */
+    fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
+    dbBranchLease?: DbBranchLease;
+    /**
+     * Set to true by `ReplayBranch` the first time customer code actually
+     * obtains `databaseUrl` for this item. Reported on the trace completion inside
+     * `db_snapshot_usage` so the server can distinguish "branch was
+     * provisioned and exposed" from "branch URL was actually consumed".
+     * Any future consumption path that hands the URL to customer code by
+     * other means (e.g. a process-isolated runner writing an env overlay)
+     * must also set this.
+     */
+    dbSnapshotAccessed?: boolean;
+    /**
+     * Collector for the replay item's trace-persistence work. When present,
+     * the root span's send path pushes a promise that resolves only after
+     * every span upload AND the trace completion have been sent (registered
+     * synchronously at send time, so the replay runner can await it after
+     * the wrapped fn resolves). This is what lets replay guarantee traces
+     * are persisted server-side before `completeReplay` builds the
+     * trace-ID mapping. Absent outside replay, where sends stay
+     * fire-and-forget.
+     */
+    pendingPersistence?: Promise<unknown>[];
+}
+
 /**
  * HTTP client utilities for Bitfab API requests.
  *
@@ -622,41 +740,20 @@ declare class BitfabOpenAIAgentHandler {
 }
 
 /**
- * Per-trace environment exposed to customer code during replay.
- *
- * The customer instantiates one `ReplayEnvironment` and passes it to
- * `bitfab.replay({ environment })`. Inside the replayed function they read
- * `env.databaseUrl` (and friends) to pick up the per-trace branch URL the
- * Bitfab service resolved from the source trace's snapshot reference.
- *
- * The constructor takes how each branch should be sized and warmed. That lives
- * here rather than on the replay options because the settings only mean
- * anything for a replay that has an environment.
- *
- * Outside replay, accessing `env.databaseUrl` throws. Customer code uses
- * the env only on the replay path; live request code keeps reading
- * `process.env.DATABASE_URL` the normal way.
- *
- * Concurrency-safe: getters resolve through the replay AsyncLocalStorage
- * context, so each in-flight replay item sees its own per-trace values
- * even when the SDK runs items in parallel.
+ * Replay historical traces through a function and create a test run.
  *
- * Internally, the resolved per-item state is a `DbBranchLease` (see
- * replayContext.ts) - that's the SDK ↔ server protocol term. We expose
- * its useful fields directly here so customer code never sees the word.
+ * The replay flow has three phases:
+ * 1. Start: fetches historical traces from the server and creates a test run
+ * 2. Execute: re-runs each trace's inputs through the provided function locally
+ * 3. Complete: marks the test run as completed on the server
  */
-interface ReplayEnvironmentSnapshot {
-    databaseUrl: string;
-    expiresAt: string;
-    providerConsoleUrl?: string;
-    readOnly?: boolean;
-    region?: string;
-    traceId: string;
-}
+
+type MockStrategy = "none" | "all" | "marked";
 /**
- * Per-lease settings for the DB-snapshot branch a replay item runs against.
- * Passed to the `ReplayEnvironment` constructor, since branching only happens
- * for a replay that has an environment.
+ * How the DB-snapshot branch each replay item runs against is sized and warmed.
+ *
+ * Passing this object at all is what turns database branching on, so `{}` means
+ * "branch every item, with the mirror project's own defaults".
  */
 interface DbBranchOptions {
     /**
@@ -675,68 +772,12 @@ interface DbBranchOptions {
     maxCu?: number;
     /**
      * SQL that warms the branch's cache. The server appends it to the branch's
-     * readiness check, so it runs BEFORE your function sees the lease and its
-     * time is not charged to the replayed call. Invalid SQL fails the lease
-     * rather than silently leaving the branch cold.
+     * readiness check, so it runs BEFORE your function sees the branch and its
+     * time is not charged to the replayed call. Invalid SQL fails the branch
+     * rather than silently leaving it cold.
      */
     warmupSql?: string;
 }
-declare class ReplayEnvironment {
-    /**
-     * The branch settings this environment was constructed with, readable
-     * anywhere. Every other accessor reports the lease the server resolved and
-     * is therefore replay-only.
-     */
-    readonly dbBranch: DbBranchOptions;
-    constructor(options?: DbBranchOptions);
-    /**
-     * The per-trace branch URL for the item currently being replayed.
-     * Throws if read outside a replay item.
-     */
-    get databaseUrl(): string;
-    /** When the per-trace branch URL stops being valid. ISO-8601. */
-    get expiresAt(): string;
-    /** Deep link to the branch in the provider console, if available. */
-    get providerConsoleUrl(): string | undefined;
-    /**
-     * True if the branch is read-only. Customer code can use this to skip
-     * write operations during replay when the provider returned a read-only
-     * lease.
-     */
-    get readOnly(): boolean | undefined;
-    /**
-     * The branch's region, e.g. `aws-us-east-1`. A compute runs in its project's
-     * region, so a replay runner elsewhere pays that round trip on every query.
-     */
-    get region(): string | undefined;
-    /** The historical trace ID that produced the input for this replay item. */
-    get traceId(): string;
-    /** True when read inside a replay item that has a resolved branch. */
-    get active(): boolean;
-    /** Non-throwing variant for callers that handle the inactive case. */
-    snapshot(): ReplayEnvironmentSnapshot | null;
-    /**
-     * Record on the replay context that customer code obtained the branch
-     * URL. Only `databaseUrl` and `snapshot()` count - `active`, `readOnly`
-     * and friends inspect the lease without exposing the connection string,
-     * so they don't prove the replayed code could have connected to the
-     * branch.
-     */
-    private markAccessed;
-    private read;
-    private require;
-}
-
-/**
- * Replay historical traces through a function and create a test run.
- *
- * The replay flow has three phases:
- * 1. Start: fetches historical traces from the server and creates a test run
- * 2. Execute: re-runs each trace's inputs through the provided function locally
- * 3. Complete: marks the test run as completed on the server
- */
-
-type MockStrategy = "none" | "all" | "marked";
 interface ReplayOptions {
     /**
      * Maximum number of traces to replay (1-100, default 5). Ignored when
@@ -779,13 +820,18 @@ interface ReplayOptions {
      */
     mockOverride?: MockOverride | MockOverride[];
     /**
-     * Per-trace environment. When the source trace carries a DB branching
-     * snapshot, the SDK populates `environment.databaseUrl` before invoking
-     * `fn` for that item and resets it after. Customer code reads from the
-     * environment to pick up the per-trace branch URL. Compute size and cache
-     * warm-up for each branch are configured on the environment's constructor.
+     * Run each item against a database branch restored to the state its source
+     * trace saw. Passing this object at all turns branching on, so `{}` enables
+     * it with the mirror project's own sizing; the fields tune how each branch is
+     * sized and warmed. Inside `fn`, read the resolved branch with
+     * `getCurrentReplayBranch()`.
+     *
+     * Items whose source trace carried no DB snapshot reference get no branch and
+     * run against the live database. An item whose branch was requested but could
+     * not be resolved fails instead of running, so a replay never silently
+     * reports a result that did not use the historical data you asked for.
      */
-    environment?: ReplayEnvironment;
+    dbBranch?: DbBranchOptions;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
@@ -1001,6 +1047,58 @@ interface ReplayResult<T> {
     testRunUrl: string;
 }
 
+/**
+ * The database branch a single replay item runs against.
+ *
+ * `getCurrentReplayBranch()` hands you one inside a replayed function when the
+ * source trace carried a DB snapshot reference and the Bitfab service resolved
+ * a branch from it. Outside a replay item, or when no branch was resolved, that
+ * accessor returns null and your code keeps reading `process.env.DATABASE_URL`
+ * the normal way.
+ *
+ * Immutable and scoped to one item: the accessor builds it from the replay
+ * AsyncLocalStorage context, so parallel replay items each see their own branch
+ * and no lease state lives on a long-lived object.
+ *
+ * Internally the resolved per-item state is a `DbBranchLease` (see
+ * replayContext.ts), the SDK/server protocol term. Its useful fields are
+ * exposed directly here so customer code never sees the word.
+ */
+
+declare class ReplayBranch {
+    #private;
+    /** When this branch's URL stops being valid. ISO-8601. */
+    readonly expiresAt: string;
+    /** Deep link to the branch in the provider console, if available. */
+    readonly providerConsoleUrl?: string;
+    /**
+     * True if the branch is read-only. Use it to skip write operations during
+     * replay when the provider returned a read-only lease.
+     */
+    readonly readOnly?: boolean;
+    /**
+     * The branch's region, e.g. `aws-us-east-1`. A compute runs in its project's
+     * region, so a replay runner elsewhere pays that round trip on every query.
+     */
+    readonly region?: string;
+    /** The historical trace ID that produced the input for this replay item. */
+    readonly traceId: string;
+    /** @internal Built by `getCurrentReplayBranch()`; never constructed by callers. */
+    constructor(lease: DbBranchLease, traceId: string, context: ReplayContext);
+    /**
+     * Connection string for this item's branch. Point your database client at it
+     * instead of the live database for the duration of the replayed call.
+     *
+     * Reading it records on the trace that the replayed code obtained the branch
+     * URL, which is what separates "a branch was provisioned" from "the branch
+     * was actually used". The other fields inspect the lease without exposing the
+     * connection string, so they deliberately do not record anything. That is
+     * also why this is a getter and not a plain field: the URL is absent from
+     * `JSON.stringify(branch)` and from logging the object.
+     */
+    get databaseUrl(): string;
+}
+
 /**
  * Tracing utilities for external trace submission to Bitfab.
  *
@@ -1240,6 +1338,23 @@ interface CurrentTrace {
  * Returns a no-op object if called outside of a span context (methods do nothing).
  */
 declare function getCurrentSpan(): CurrentSpan;
+/**
+ * Get the database branch the current replay item is running against.
+ *
+ * Call this from inside a function being replayed with `replay({ dbBranch })`
+ * and point your database client at `branch.databaseUrl` so the replay reads
+ * the data as it was at trace time:
+ *
+ * ```ts
+ * const branch = getCurrentReplayBranch()
+ * const url = branch?.databaseUrl ?? process.env.DATABASE_URL
+ * ```
+ *
+ * Returns null outside a replay item, and for an item whose source trace
+ * carried no DB snapshot reference, so live request code takes the same path
+ * it always did.
+ */
+declare function getCurrentReplayBranch(): ReplayBranch | null;
 /**
  * Get a handle to the current active trace.
  *
@@ -1347,12 +1462,6 @@ interface SpanOptions {
  * Client for making provider-based API calls via BAML.
  */
 declare class Bitfab {
-    /**
-     * Per-trace environment for `replay({ environment })`. Construct one,
-     * pass it to replay, and read `env.databaseUrl` inside the replayed
-     * function to pick up the per-trace branch URL.
-     */
-    static readonly ReplayEnvironment: typeof ReplayEnvironment;
     private readonly apiKeyConfig;
     /** Cached only once a non-empty key is found, so an early resolve (before env loaded) can't poison a later one. */
     private resolvedApiKey;
@@ -1854,7 +1963,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.32.0";
+declare const __version__ = "0.33.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1922,4 +2031,4 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress };