@bitfab/sdk 0.36.12 → 0.38.0

package/dist/index.d.cts

@@ -182,8 +182,9 @@ interface MockOverride {
  * 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
+ * inline, even when overrides are present. Under a non-`all` path that needs a
+ * tree (`marked`, or `none` with overrides), they are absent and the recorded
+ * output is fetched on demand via `externalSpanId` - see
  * {@link ReplayContext.fetchSpanOutput}.
  */
 interface MockSpan {
@@ -222,6 +223,39 @@ interface DbBranchLease {
      */
     region?: string;
 }
+/**
+ * How long each phase of provisioning one replay branch took, measured
+ * server-side. A runner in another region sees these plus its own round trip.
+ *
+ * Durations, not instants: an instant is approximately `startedAt` plus the
+ * running sum, and per-phase wall-clock stamps would make clock skew between
+ * the server and your runner look like latency. Approximately, because
+ * `totalMs` is the resolve's true wall time and covers a little work no phase
+ * owns, so the phases account for it without summing to it exactly.
+ *
+ * `startedAt` and `totalMs` are always present. The phases are optional
+ * because a failed resolve reports only the ones it reached, and `totalMs` is
+ * then time-to-failure. On success every phase is present except `warmupMs`,
+ * which is absent when no warm-up SQL was supplied.
+ */
+interface DbBranchTimings {
+    /** When the resolve began, ISO. */
+    startedAt: string;
+    /** Resolving the project, plus its retention and region reads. */
+    projectResolveMs?: number;
+    /** Creating the branch, through its provider operations reaching terminal. */
+    branchCreateMs?: number;
+    /** Resolving the connection URI. 0 when the provider returns one inline. */
+    connectionUriMs?: number;
+    /** The compute accepting a connection. */
+    computeConnectMs?: number;
+    /** The branch answering a readiness query. */
+    baseProbeMs?: number;
+    /** Your warm-up SQL. Absent when you supplied none. */
+    warmupMs?: number;
+    /** The whole resolve, or time-to-failure when it threw. */
+    totalMs: number;
+}
 /**
  * Wire shape of the caller's `ReplayOptions.dbBranch`, sent to
  * `/api/sdk/replay/start` and applied per lease.
@@ -267,12 +301,21 @@ interface ReplayContext {
     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.
+     * `externalSpanId`. Present ONLY on a non-`all` path that needs a tree
+     * (`marked`, or `none` with overrides); absent under `mock: "all"`, where
+     * outputs are inline even when overrides are present. Its presence is the
+     * signal that outputs must be fetched rather than read inline.
      */
     fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
     dbBranchLease?: DbBranchLease;
+    /**
+     * Server-measured provisioning timings for this item's branch, echoed back
+     * on the trace completion so the trace records what it cost to set up. Kept
+     * off `ReplayBranch`: customer code reads that mid-replay to reach the
+     * branch, and provisioning latency is a property of the run, not of the
+     * connection.
+     */
+    dbBranchTimings?: DbBranchTimings;
     /**
      * Set to true by `ReplayBranch` the first time customer code actually
      * obtains `databaseUrl` for this item. Reported on the trace completion inside
@@ -568,6 +611,7 @@ declare class HttpClient {
             code: string;
             message: string;
         } | null;
+        timings: DbBranchTimings | null;
     }>;
     /** Release a previously-resolved DB branch by deleting its Neon branch. Idempotent server-side. */
     releaseDbBranchLease(neonBranchId: string): Promise<void>;
@@ -626,6 +670,13 @@ interface StartReplayResponse {
             code: string;
             message: string;
         };
+        /**
+         * How long provisioning took, per phase. Sits beside the two fields above
+         * rather than inside either: it is reported on both outcomes, complete on
+         * success and partial up to the failing phase on error. Absent from
+         * servers that predate it.
+         */
+        dbBranchTimings?: DbBranchTimings;
     }>;
 }
 interface ExternalSpanResponse {
@@ -1177,9 +1228,9 @@ interface DbBranchOptions {
 }
 interface ReplayOptions {
     /**
-     * Maximum number of traces to replay (1-100, default 5). Ignored when
-     * `traceIds` is passed (with a warning): an explicit ID list already
-     * determines how many traces replay.
+     * Maximum number of traces to replay (1-5,000, default 5). Ignored when
+     * `traceIds` is passed (with a warning), or when `datasetId` is passed,
+     * because either source already determines how many traces replay.
      */
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
@@ -1209,7 +1260,8 @@ interface ReplayOptions {
      * Mock strategy for child spans during replay.
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
      * - "none": everything runs real code
-     * - "all": every child withSpan returns historical output
+     * - "all": every matched recorded child withSpan returns historical output;
+     *   a missing occurrence fails the replay item closed
      */
     mock?: MockStrategy;
     /**
@@ -1229,9 +1281,10 @@ interface ReplayOptions {
      * 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.
+     * use the app's normal database path. Unsafe calls on that path still require
+     * replay mocking. An item whose branch was requested but could not be resolved
+     * fails instead of running, so replay never silently reports a result that did
+     * not use the historical data you asked for.
      */
     dbBranch?: DbBranchOptions | boolean;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
@@ -1339,42 +1392,52 @@ interface ReplayItemFinishProgress {
     /** Of the completed items, how many have `item.error` set. */
     errored: number;
     /**
-     * The single item that just finished to produce this event. `traceId` is null
-     * at this stage (the server replay id isn't known until the run completes);
-     * `originalTraceId` is the original (historical) trace that was replayed (so
-     * a UI can identify or link it); `error` is its replay error, or null when it
-     * ran ok; `durationMs` is how long this one trace took to replay. Lets a
-     * progress UI show per-trace pass/fail and timing as the run streams, without
-     * waiting for the full {@link ReplayResult}.
+     * The single item that just finished to produce this event. Field-for-field
+     * the same shape and meaning as {@link ReplayItem}, so a progress UI and a
+     * final-result UI read one contract. `traceId` is null at this stage (the
+     * server replay id arrives at completion), and `tokens` is null for the same
+     * reason: the replayed run's usage is aggregated server-side by
+     * completeReplay. `durationMs` is how long this item took to replay; the
+     * `original*` fields describe the trace it replayed.
      */
-    item: {
-        /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
-        traceId?: string | null;
-        /** Bitfab trace ID of the original (historical) trace being replayed. */
-        originalTraceId: string | null;
-        /** External span ID the recorded inputs were read from (the original root span). */
-        originalSpanId?: string | null;
-        /** @deprecated alias for `originalTraceId`. */
-        sourceTraceId: string | null;
-        /** @deprecated alias for `originalSpanId`. */
-        sourceSpanId?: string | null;
-        /** Deserialized inputs from the original trace. */
-        input?: unknown[];
-        /** The result returned by the replayed function, or undefined on error. */
-        result?: unknown;
-        /** The original output from the historical trace. */
-        originalOutput?: unknown;
-        /** Backward-compatible message for either error kind. */
-        error: string | null;
-        /** The actual value thrown by the replayed customer function. */
-        traceError: unknown | null;
-        /** The actual value thrown while Bitfab prepared this replay item. */
-        replayError: unknown | null;
-        durationMs: number | null;
-        tokens?: TokenUsage | null;
-        model?: string | null;
-        dbSnapshotRef?: DbSnapshotRef | null;
-    };
+    item: ReplayProgressItem;
+}
+/** See {@link ReplayItemFinishProgress.item}. Mirrors {@link ReplayItem}. */
+interface ReplayProgressItem {
+    /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
+    traceId?: string | null;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId: string | null;
+    /** External span ID the recorded inputs were read from (the original root span). */
+    originalSpanId?: string | null;
+    /** @deprecated alias for `originalTraceId`. */
+    sourceTraceId: string | null;
+    /** @deprecated alias for `originalSpanId`. */
+    sourceSpanId?: string | null;
+    /** Deserialized inputs from the original trace. */
+    input?: unknown[];
+    /** The result returned by the replayed function, or undefined on error. */
+    result?: unknown;
+    /** The original output from the historical trace. */
+    originalOutput?: unknown;
+    /** Backward-compatible message for either error kind. */
+    error: string | null;
+    /** The actual value thrown by the replayed customer function. */
+    traceError?: unknown | null;
+    /** The actual value thrown while Bitfab prepared this replay item. */
+    replayError?: unknown | null;
+    /** How long the replayed function took on this run. */
+    durationMs?: number | null;
+    /** The original trace's duration, tokens, and model. */
+    originalDurationMs?: number | null;
+    originalTokens?: TokenUsage | null;
+    originalModel?: string | null;
+    /** Always null here: the replayed run's usage is only known at completion. */
+    tokens?: TokenUsage | null;
+    /** @deprecated renamed to `originalModel`. */
+    model?: string | null;
+    dbSnapshotRef?: DbSnapshotRef | null;
+    dbBranchTimings?: DbBranchTimings | null;
 }
 /**
  * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
@@ -1478,17 +1541,32 @@ interface ReplayItem<T> {
      * such as database warmup, input hydration, or mock preparation.
      */
     replayError: unknown | null;
-    /** Original trace duration in milliseconds, or null if timestamps are missing. */
+    /**
+     * How long the replayed function took on this run, in ms. Null if the item
+     * failed before it ran. Compare against
+     * {@link ReplayItem.originalDurationMs} for the before/after.
+     */
     durationMs: number | null;
+    /** The original trace's duration in ms, or null if its timestamps are missing. */
+    originalDurationMs: number | null;
+    /**
+     * Token usage recorded on the original trace, or null if it captured none.
+     * The "old" side of a token delta; {@link ReplayItem.tokens} is the new one.
+     */
+    originalTokens: TokenUsage | null;
+    /** Model name from the original trace, or null if not captured. */
+    originalModel: string | null;
     /**
      * Token usage from the REPLAYED run (this item's new execution), aggregated
      * server-side from the spans it produced, or null if the run captured no
-     * token data. This is the "new" side of a token delta: compare it against
-     * the original trace's recorded usage to see how the code change moved cost.
-     * Matches what Studio's experiments view shows.
+     * token data. Compare against {@link ReplayItem.originalTokens} to see how
+     * the code change moved cost. Matches what Studio's experiments view shows.
+     *
+     * Unprefixed because the replay is this item's subject: anything describing
+     * the trace being replayed carries `original`.
      */
     tokens: TokenUsage | null;
-    /** Model name from the original trace, or null if not captured. */
+    /** @deprecated renamed to {@link ReplayItem.originalModel}. */
     model: string | null;
     /**
      * The DB snapshot ref the SDK captured at trace open. Useful for debugging
@@ -1497,6 +1575,14 @@ interface ReplayItem<T> {
      * without `dbSnapshot` configured.
      */
     dbSnapshotRef: DbSnapshotRef | null;
+    /**
+     * How long this item's DB branch took to provision, per phase, measured
+     * server-side. Present whenever a branch was attempted, on both outcomes:
+     * complete on success, partial up to the failing phase when the resolve
+     * failed. Null when no branch was asked for, when the source trace carried
+     * no snapshot ref, or against a server that predates timings.
+     */
+    dbBranchTimings: DbBranchTimings | null;
 }
 
 interface ReplayResult<T> {
@@ -1966,7 +2052,9 @@ interface SpanOptions {
      *
      * Use this for child spans that are expensive (paid LLM/API calls),
      * slow, or non-deterministic - the root function still runs real code,
-     * only the marked descendants return their recorded output.
+     * only the marked descendants return their recorded output. If a selected
+     * occurrence is unavailable, replay fails the item without executing the
+     * real child.
      */
     mockOnReplay?: boolean;
     /**
@@ -2575,7 +2663,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.12";
+declare const __version__ = "0.38.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2643,4 +2731,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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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, serializeReplayResult };
+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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayProgressItem, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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, serializeReplayResult };

package/dist/index.d.ts

@@ -182,8 +182,9 @@ interface MockOverride {
  * 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
+ * inline, even when overrides are present. Under a non-`all` path that needs a
+ * tree (`marked`, or `none` with overrides), they are absent and the recorded
+ * output is fetched on demand via `externalSpanId` - see
  * {@link ReplayContext.fetchSpanOutput}.
  */
 interface MockSpan {
@@ -222,6 +223,39 @@ interface DbBranchLease {
      */
     region?: string;
 }
+/**
+ * How long each phase of provisioning one replay branch took, measured
+ * server-side. A runner in another region sees these plus its own round trip.
+ *
+ * Durations, not instants: an instant is approximately `startedAt` plus the
+ * running sum, and per-phase wall-clock stamps would make clock skew between
+ * the server and your runner look like latency. Approximately, because
+ * `totalMs` is the resolve's true wall time and covers a little work no phase
+ * owns, so the phases account for it without summing to it exactly.
+ *
+ * `startedAt` and `totalMs` are always present. The phases are optional
+ * because a failed resolve reports only the ones it reached, and `totalMs` is
+ * then time-to-failure. On success every phase is present except `warmupMs`,
+ * which is absent when no warm-up SQL was supplied.
+ */
+interface DbBranchTimings {
+    /** When the resolve began, ISO. */
+    startedAt: string;
+    /** Resolving the project, plus its retention and region reads. */
+    projectResolveMs?: number;
+    /** Creating the branch, through its provider operations reaching terminal. */
+    branchCreateMs?: number;
+    /** Resolving the connection URI. 0 when the provider returns one inline. */
+    connectionUriMs?: number;
+    /** The compute accepting a connection. */
+    computeConnectMs?: number;
+    /** The branch answering a readiness query. */
+    baseProbeMs?: number;
+    /** Your warm-up SQL. Absent when you supplied none. */
+    warmupMs?: number;
+    /** The whole resolve, or time-to-failure when it threw. */
+    totalMs: number;
+}
 /**
  * Wire shape of the caller's `ReplayOptions.dbBranch`, sent to
  * `/api/sdk/replay/start` and applied per lease.
@@ -267,12 +301,21 @@ interface ReplayContext {
     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.
+     * `externalSpanId`. Present ONLY on a non-`all` path that needs a tree
+     * (`marked`, or `none` with overrides); absent under `mock: "all"`, where
+     * outputs are inline even when overrides are present. Its presence is the
+     * signal that outputs must be fetched rather than read inline.
      */
     fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
     dbBranchLease?: DbBranchLease;
+    /**
+     * Server-measured provisioning timings for this item's branch, echoed back
+     * on the trace completion so the trace records what it cost to set up. Kept
+     * off `ReplayBranch`: customer code reads that mid-replay to reach the
+     * branch, and provisioning latency is a property of the run, not of the
+     * connection.
+     */
+    dbBranchTimings?: DbBranchTimings;
     /**
      * Set to true by `ReplayBranch` the first time customer code actually
      * obtains `databaseUrl` for this item. Reported on the trace completion inside
@@ -568,6 +611,7 @@ declare class HttpClient {
             code: string;
             message: string;
         } | null;
+        timings: DbBranchTimings | null;
     }>;
     /** Release a previously-resolved DB branch by deleting its Neon branch. Idempotent server-side. */
     releaseDbBranchLease(neonBranchId: string): Promise<void>;
@@ -626,6 +670,13 @@ interface StartReplayResponse {
             code: string;
             message: string;
         };
+        /**
+         * How long provisioning took, per phase. Sits beside the two fields above
+         * rather than inside either: it is reported on both outcomes, complete on
+         * success and partial up to the failing phase on error. Absent from
+         * servers that predate it.
+         */
+        dbBranchTimings?: DbBranchTimings;
     }>;
 }
 interface ExternalSpanResponse {
@@ -1177,9 +1228,9 @@ interface DbBranchOptions {
 }
 interface ReplayOptions {
     /**
-     * Maximum number of traces to replay (1-100, default 5). Ignored when
-     * `traceIds` is passed (with a warning): an explicit ID list already
-     * determines how many traces replay.
+     * Maximum number of traces to replay (1-5,000, default 5). Ignored when
+     * `traceIds` is passed (with a warning), or when `datasetId` is passed,
+     * because either source already determines how many traces replay.
      */
     limit?: number;
     /** Optional list of specific trace IDs to replay (max 100). */
@@ -1209,7 +1260,8 @@ interface ReplayOptions {
      * Mock strategy for child spans during replay.
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked (default)
      * - "none": everything runs real code
-     * - "all": every child withSpan returns historical output
+     * - "all": every matched recorded child withSpan returns historical output;
+     *   a missing occurrence fails the replay item closed
      */
     mock?: MockStrategy;
     /**
@@ -1229,9 +1281,10 @@ interface ReplayOptions {
      * 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.
+     * use the app's normal database path. Unsafe calls on that path still require
+     * replay mocking. An item whose branch was requested but could not be resolved
+     * fails instead of running, so replay never silently reports a result that did
+     * not use the historical data you asked for.
      */
     dbBranch?: DbBranchOptions | boolean;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
@@ -1339,42 +1392,52 @@ interface ReplayItemFinishProgress {
     /** Of the completed items, how many have `item.error` set. */
     errored: number;
     /**
-     * The single item that just finished to produce this event. `traceId` is null
-     * at this stage (the server replay id isn't known until the run completes);
-     * `originalTraceId` is the original (historical) trace that was replayed (so
-     * a UI can identify or link it); `error` is its replay error, or null when it
-     * ran ok; `durationMs` is how long this one trace took to replay. Lets a
-     * progress UI show per-trace pass/fail and timing as the run streams, without
-     * waiting for the full {@link ReplayResult}.
+     * The single item that just finished to produce this event. Field-for-field
+     * the same shape and meaning as {@link ReplayItem}, so a progress UI and a
+     * final-result UI read one contract. `traceId` is null at this stage (the
+     * server replay id arrives at completion), and `tokens` is null for the same
+     * reason: the replayed run's usage is aggregated server-side by
+     * completeReplay. `durationMs` is how long this item took to replay; the
+     * `original*` fields describe the trace it replayed.
      */
-    item: {
-        /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
-        traceId?: string | null;
-        /** Bitfab trace ID of the original (historical) trace being replayed. */
-        originalTraceId: string | null;
-        /** External span ID the recorded inputs were read from (the original root span). */
-        originalSpanId?: string | null;
-        /** @deprecated alias for `originalTraceId`. */
-        sourceTraceId: string | null;
-        /** @deprecated alias for `originalSpanId`. */
-        sourceSpanId?: string | null;
-        /** Deserialized inputs from the original trace. */
-        input?: unknown[];
-        /** The result returned by the replayed function, or undefined on error. */
-        result?: unknown;
-        /** The original output from the historical trace. */
-        originalOutput?: unknown;
-        /** Backward-compatible message for either error kind. */
-        error: string | null;
-        /** The actual value thrown by the replayed customer function. */
-        traceError: unknown | null;
-        /** The actual value thrown while Bitfab prepared this replay item. */
-        replayError: unknown | null;
-        durationMs: number | null;
-        tokens?: TokenUsage | null;
-        model?: string | null;
-        dbSnapshotRef?: DbSnapshotRef | null;
-    };
+    item: ReplayProgressItem;
+}
+/** See {@link ReplayItemFinishProgress.item}. Mirrors {@link ReplayItem}. */
+interface ReplayProgressItem {
+    /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
+    traceId?: string | null;
+    /** Bitfab trace ID of the original (historical) trace being replayed. */
+    originalTraceId: string | null;
+    /** External span ID the recorded inputs were read from (the original root span). */
+    originalSpanId?: string | null;
+    /** @deprecated alias for `originalTraceId`. */
+    sourceTraceId: string | null;
+    /** @deprecated alias for `originalSpanId`. */
+    sourceSpanId?: string | null;
+    /** Deserialized inputs from the original trace. */
+    input?: unknown[];
+    /** The result returned by the replayed function, or undefined on error. */
+    result?: unknown;
+    /** The original output from the historical trace. */
+    originalOutput?: unknown;
+    /** Backward-compatible message for either error kind. */
+    error: string | null;
+    /** The actual value thrown by the replayed customer function. */
+    traceError?: unknown | null;
+    /** The actual value thrown while Bitfab prepared this replay item. */
+    replayError?: unknown | null;
+    /** How long the replayed function took on this run. */
+    durationMs?: number | null;
+    /** The original trace's duration, tokens, and model. */
+    originalDurationMs?: number | null;
+    originalTokens?: TokenUsage | null;
+    originalModel?: string | null;
+    /** Always null here: the replayed run's usage is only known at completion. */
+    tokens?: TokenUsage | null;
+    /** @deprecated renamed to `originalModel`. */
+    model?: string | null;
+    dbSnapshotRef?: DbSnapshotRef | null;
+    dbBranchTimings?: DbBranchTimings | null;
 }
 /**
  * @deprecated Use {@link ReplayItemFinishProgress}. This legacy shape also
@@ -1478,17 +1541,32 @@ interface ReplayItem<T> {
      * such as database warmup, input hydration, or mock preparation.
      */
     replayError: unknown | null;
-    /** Original trace duration in milliseconds, or null if timestamps are missing. */
+    /**
+     * How long the replayed function took on this run, in ms. Null if the item
+     * failed before it ran. Compare against
+     * {@link ReplayItem.originalDurationMs} for the before/after.
+     */
     durationMs: number | null;
+    /** The original trace's duration in ms, or null if its timestamps are missing. */
+    originalDurationMs: number | null;
+    /**
+     * Token usage recorded on the original trace, or null if it captured none.
+     * The "old" side of a token delta; {@link ReplayItem.tokens} is the new one.
+     */
+    originalTokens: TokenUsage | null;
+    /** Model name from the original trace, or null if not captured. */
+    originalModel: string | null;
     /**
      * Token usage from the REPLAYED run (this item's new execution), aggregated
      * server-side from the spans it produced, or null if the run captured no
-     * token data. This is the "new" side of a token delta: compare it against
-     * the original trace's recorded usage to see how the code change moved cost.
-     * Matches what Studio's experiments view shows.
+     * token data. Compare against {@link ReplayItem.originalTokens} to see how
+     * the code change moved cost. Matches what Studio's experiments view shows.
+     *
+     * Unprefixed because the replay is this item's subject: anything describing
+     * the trace being replayed carries `original`.
      */
     tokens: TokenUsage | null;
-    /** Model name from the original trace, or null if not captured. */
+    /** @deprecated renamed to {@link ReplayItem.originalModel}. */
     model: string | null;
     /**
      * The DB snapshot ref the SDK captured at trace open. Useful for debugging
@@ -1497,6 +1575,14 @@ interface ReplayItem<T> {
      * without `dbSnapshot` configured.
      */
     dbSnapshotRef: DbSnapshotRef | null;
+    /**
+     * How long this item's DB branch took to provision, per phase, measured
+     * server-side. Present whenever a branch was attempted, on both outcomes:
+     * complete on success, partial up to the failing phase when the resolve
+     * failed. Null when no branch was asked for, when the source trace carried
+     * no snapshot ref, or against a server that predates timings.
+     */
+    dbBranchTimings: DbBranchTimings | null;
 }
 
 interface ReplayResult<T> {
@@ -1966,7 +2052,9 @@ interface SpanOptions {
      *
      * Use this for child spans that are expensive (paid LLM/API calls),
      * slow, or non-deterministic - the root function still runs real code,
-     * only the marked descendants return their recorded output.
+     * only the marked descendants return their recorded output. If a selected
+     * occurrence is unavailable, replay fails the item without executing the
+     * real child.
      */
     mockOnReplay?: boolean;
     /**
@@ -2575,7 +2663,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.36.12";
+declare const __version__ = "0.38.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2643,4 +2731,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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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, serializeReplayResult };
+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 CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayProgressItem, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, 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, serializeReplayResult };

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-OCJSHTJR.js";
+} from "./chunk-LCGQUVKR.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
@@ -23,7 +23,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-VUYTATF5.js";
+} from "./chunk-SSNTMROV.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,