@bitfab/sdk 0.30.2 → 0.31.0

package/dist/index.d.cts

@@ -646,6 +646,7 @@ interface ReplayEnvironmentSnapshot {
     expiresAt: string;
     providerConsoleUrl?: string;
     readOnly?: boolean;
+    region?: string;
     traceId: string;
 }
 declare class ReplayEnvironment {
@@ -664,6 +665,11 @@ declare class ReplayEnvironment {
      * 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. */
@@ -692,6 +698,33 @@ declare class ReplayEnvironment {
  */
 
 type MockStrategy = "none" | "all" | "marked";
+/**
+ * Per-lease settings for the DB-snapshot branch a replay item runs against.
+ * Only read when `environment` is set, since that is what turns branching on.
+ */
+interface DbBranchOptions {
+    /**
+     * Autoscaling floor for the branch's compute, in Neon Compute Units (0.25 to
+     * 56). Omit to keep the mirror project's own default. Raise it when the
+     * mirror is provisioned smaller than the database it stands in for, so
+     * replay latency reflects your code rather than a cold, undersized branch.
+     */
+    minCu?: number;
+    /**
+     * Autoscaling ceiling for the branch's compute, in Neon Compute Units.
+     * Setting it equal to `minCu` pins the size, which keeps items comparable:
+     * otherwise a later item can run against an endpoint that has already
+     * scaled up and post a better number for the same code.
+     */
+    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.
+     */
+    warmupSql?: string;
+}
 interface ReplayOptions {
     /**
      * Maximum number of traces to replay (1-100, default 5). Ignored when
@@ -740,6 +773,8 @@ interface ReplayOptions {
      * environment to pick up the per-trace branch URL.
      */
     environment?: ReplayEnvironment;
+    /** Compute size and cache warm-up for the per-item DB snapshot branch. */
+    dbBranch?: DbBranchOptions;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
@@ -1808,7 +1843,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.30.2";
+declare const __version__ = "0.31.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1876,4 +1911,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 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, 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 };

package/dist/index.d.ts

@@ -646,6 +646,7 @@ interface ReplayEnvironmentSnapshot {
     expiresAt: string;
     providerConsoleUrl?: string;
     readOnly?: boolean;
+    region?: string;
     traceId: string;
 }
 declare class ReplayEnvironment {
@@ -664,6 +665,11 @@ declare class ReplayEnvironment {
      * 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. */
@@ -692,6 +698,33 @@ declare class ReplayEnvironment {
  */
 
 type MockStrategy = "none" | "all" | "marked";
+/**
+ * Per-lease settings for the DB-snapshot branch a replay item runs against.
+ * Only read when `environment` is set, since that is what turns branching on.
+ */
+interface DbBranchOptions {
+    /**
+     * Autoscaling floor for the branch's compute, in Neon Compute Units (0.25 to
+     * 56). Omit to keep the mirror project's own default. Raise it when the
+     * mirror is provisioned smaller than the database it stands in for, so
+     * replay latency reflects your code rather than a cold, undersized branch.
+     */
+    minCu?: number;
+    /**
+     * Autoscaling ceiling for the branch's compute, in Neon Compute Units.
+     * Setting it equal to `minCu` pins the size, which keeps items comparable:
+     * otherwise a later item can run against an endpoint that has already
+     * scaled up and post a better number for the same code.
+     */
+    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.
+     */
+    warmupSql?: string;
+}
 interface ReplayOptions {
     /**
      * Maximum number of traces to replay (1-100, default 5). Ignored when
@@ -740,6 +773,8 @@ interface ReplayOptions {
      * environment to pick up the per-trace branch URL.
      */
     environment?: ReplayEnvironment;
+    /** Compute size and cache warm-up for the per-item DB snapshot branch. */
+    dbBranch?: DbBranchOptions;
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
@@ -1808,7 +1843,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.30.2";
+declare const __version__ = "0.31.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1876,4 +1911,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 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, 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 };

package/dist/index.js

@@ -14,12 +14,12 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-CPEQSNVE.js";
+} from "./chunk-A7K5JOBV.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
   reportReplayProgress
-} from "./chunk-FLVQ7Q3I.js";
+} from "./chunk-6UJ3E3H5.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,

package/dist/node.cjs

@@ -531,6 +531,17 @@ __export(replay_exports, {
   replay: () => replay,
   reportReplayProgress: () => reportReplayProgress
 });
+function resolveDbBranchSettings(dbBranch) {
+  if (!dbBranch) {
+    return void 0;
+  }
+  const settings = {
+    ...dbBranch.minCu === void 0 ? {} : { minCu: dbBranch.minCu },
+    ...dbBranch.maxCu === void 0 ? {} : { maxCu: dbBranch.maxCu },
+    ...dbBranch.warmupSql === void 0 ? {} : { warmupSql: dbBranch.warmupSql }
+  };
+  return Object.keys(settings).length === 0 ? void 0 : settings;
+}
 function reportReplayProgress(progress) {
   const stderr = typeof process !== "undefined" ? process.stderr : void 0;
   if (!stderr) {
@@ -593,6 +604,7 @@ function buildMockTree(rootNode) {
 }
 async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, environment, adaptInputs) {
   const lease = environment ? serverItem.dbBranchLease : void 0;
+  const leaseError = environment ? serverItem.dbBranchLeaseError : void 0;
   let inputs = [];
   let originalOutput;
   let result;
@@ -601,6 +613,11 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
   const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
   const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
   try {
+    if (leaseError) {
+      throw new BitfabError(
+        `Replay requested a database branch for trace ${originalTraceId} but it could not be resolved (${leaseError.code}): ${leaseError.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`
+      );
+    }
     const span = await httpClient.getExternalSpan(originalSpanId);
     const spanData = span.rawData?.span_data ?? {};
     inputs = deserializeInputs(spanData);
@@ -774,7 +791,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     // includeDbBranchLease
     options?.experimentGroupId,
     options?.datasetId,
-    options?.graderIds
+    options?.graderIds,
+    resolveDbBranchSettings(options?.dbBranch)
   );
   const mockStrategy = options?.mock ?? "marked";
   const maxConcurrency = options?.maxConcurrency ?? 10;
@@ -968,7 +986,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.30.2";
+var __version__ = "0.31.0";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -1327,7 +1345,7 @@ var HttpClient = class {
    * Start a replay session by fetching historical traces.
    * Blocking call - creates a test run and returns lightweight item references.
    */
-  async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds) {
+  async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetId, graderIds, dbBranchSettings) {
     const payload = { traceFunctionKey };
     if (limit !== void 0) {
       payload.limit = limit;
@@ -1356,6 +1374,9 @@ var HttpClient = class {
     if (graderIds !== void 0) {
       payload.graderIds = graderIds;
     }
+    if (dbBranchSettings !== void 0) {
+      payload.dbBranchSettings = dbBranchSettings;
+    }
     const timeout = includeDbBranchLease ? 18e4 : 3e4;
     return this.request("/api/sdk/replay/start", payload, {
       timeout
@@ -3086,6 +3107,13 @@ var ReplayEnvironment = class {
   get readOnly() {
     return this.require().readOnly;
   }
+  /**
+   * 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() {
+    return this.require().region;
+  }
   /** The historical trace ID that produced the input for this replay item. */
   get traceId() {
     return this.require().traceId;
@@ -3130,6 +3158,7 @@ var ReplayEnvironment = class {
       expiresAt: lease.expiresAt,
       providerConsoleUrl: lease.providerConsoleUrl,
       readOnly: lease.readOnly,
+      region: lease.region,
       traceId
     };
   }