bitfab 0.13.3 → 0.13.4

package/dist/index.d.cts

@@ -145,19 +145,61 @@ declare class BitfabClaudeAgentHandler {
 }
 
 /**
- * HTTP client utilities for Bitfab API requests.
+ * Per-trace database snapshot ref capture.
  *
- * This module provides:
- * - HttpClient class for making API requests
- * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
- */
+ * When the customer configures `dbSnapshot`, every root span carries a
+ * `DbSnapshotRef` that pins the DB state at trace open by wall-clock
+ * timestamp. The Bitfab service uses that timestamp at replay time to
+ * materialize an ephemeral branch from `customer-main`.
+ *
+ * v0 is timestamp-only. LSN-based pinning is intentionally not exposed
+ * yet — the customer-LSN to replica-LSN mapping isn't built, so the
+ * mapping primitive would have no resolver to consume it. The
+ * `DbSnapshotRef.ref` field is reserved for that future use.
+ */
+/** Providers the SDK accepts for `dbSnapshot.provider`. Server-side resolver dispatches on this. */
+declare const SUPPORTED_PROVIDERS: readonly ["neon", "ardent", "dolt", "gfs", "mongodb-atlas", "dynamodb", "snowflake", "bigquery"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+    /** Discriminator for the server-side resolver. */
+    provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+    provider: DbSnapshotProvider;
+    /**
+     * The wall-clock ISO timestamp the SDK observed immediately before
+     * invoking the wrapped function. This is the moment used as the
+     * "snapshot pin" by the timestamp-based resolver path. The name encodes
+     * its provenance: SDK-observed, wall clock (not monotonic), captured
+     * before user code began executing — distinct from server-side or
+     * DB-side timestamps recorded elsewhere on the trace.
+     */
+    sdkWallClockBeforeFn: string;
+    /**
+     * Reserved for future provider-specific opaque payload (e.g. customer
+     * LSN once a source-to-replica mapping exists). Unused in v0.
+     */
+    ref?: Record<string, unknown>;
+}
+
 /**
- * Error class for Bitfab API errors.
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
  */
 declare class BitfabError extends Error {
     readonly url?: string | undefined;
     constructor(message: string, url?: string | undefined);
 }
+
+/**
+ * HTTP client utilities for Bitfab API requests.
+ *
+ * This module provides:
+ * - HttpClient class for making API requests
+ * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ */
+
 /**
  * Wait for all pending fire-and-forget operations (spans, traces) to complete.
  * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
@@ -249,6 +291,66 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+interface ReplayEnvironmentSnapshot {
+    databaseUrl: string;
+    expiresAt: string;
+    providerConsoleUrl?: string;
+    readOnly?: boolean;
+    traceId: string;
+    precision: "timestamp" | "lsn";
+}
+declare class ReplayEnvironment {
+    /**
+     * 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 historical trace ID that produced the input for this replay item. */
+    get traceId(): string;
+    /**
+     * How the resolver pinned this branch.
+     * - "timestamp": snapshot at SDK wall clock; bounded by replication lag.
+     * - "lsn": customer LSN mapped to a replica snapshot (future).
+     */
+    get precision(): "timestamp" | "lsn";
+    /** 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;
+    private read;
+    private require;
+}
+
 /**
  * Replay historical traces through a function and create a test run.
  *
@@ -285,6 +387,13 @@ interface ReplayOptions {
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked
      */
     mock?: MockStrategy;
+    /**
+     * 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.
+     */
+    environment?: ReplayEnvironment;
 }
 interface ReplayItem<T> {
     /** Deserialized inputs from the original trace. */
@@ -301,6 +410,13 @@ interface ReplayItem<T> {
     tokens: TokenUsage | null;
     /** Model name from the original trace, or null if not captured. */
     model: string | null;
+    /**
+     * The DB snapshot ref the SDK captured at trace open. Useful for debugging
+     * ("what state was this trace pinned to?") and for customers building
+     * their own resolvers. Undefined when the source trace was captured
+     * without `dbSnapshot` configured.
+     */
+    dbSnapshotRef: DbSnapshotRef | null;
 }
 
 interface ReplayResult<T> {
@@ -549,6 +665,13 @@ interface BitfabConfig {
     enabled?: boolean;
     /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
     bamlClient?: unknown;
+    /**
+     * Per-trace database snapshot config. When set, every root span captures
+     * a wall-clock timestamp (and, if `captureRef` is provided, a provider-
+     * specific point-in-time ref) so the trace can later be replayed against
+     * a branch materialized from that point.
+     */
+    dbSnapshot?: DbSnapshotConfig;
 }
 /**
  * Span types matching the backend enum.
@@ -589,6 +712,12 @@ 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 apiKey;
     private readonly serviceUrl;
     private readonly timeout;
@@ -596,6 +725,7 @@ declare class Bitfab {
     private readonly enabled;
     private readonly httpClient;
     private readonly bamlClient;
+    private readonly dbSnapshot;
     /**
      * Initialize the Bitfab client.
      *
@@ -812,6 +942,7 @@ declare class Bitfab {
         codeChangeDescription?: string;
         codeChangeFiles?: CodeChangeFile[];
         mock?: "none" | "all" | "marked";
+        environment?: ReplayEnvironment;
     }): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -875,7 +1006,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.13.3";
+declare const __version__ = "0.13.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -885,4 +1016,4 @@ declare const __version__ = "0.13.3";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DetachedTrace, type MockStrategy, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.d.ts

@@ -145,19 +145,61 @@ declare class BitfabClaudeAgentHandler {
 }
 
 /**
- * HTTP client utilities for Bitfab API requests.
+ * Per-trace database snapshot ref capture.
  *
- * This module provides:
- * - HttpClient class for making API requests
- * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
- */
+ * When the customer configures `dbSnapshot`, every root span carries a
+ * `DbSnapshotRef` that pins the DB state at trace open by wall-clock
+ * timestamp. The Bitfab service uses that timestamp at replay time to
+ * materialize an ephemeral branch from `customer-main`.
+ *
+ * v0 is timestamp-only. LSN-based pinning is intentionally not exposed
+ * yet — the customer-LSN to replica-LSN mapping isn't built, so the
+ * mapping primitive would have no resolver to consume it. The
+ * `DbSnapshotRef.ref` field is reserved for that future use.
+ */
+/** Providers the SDK accepts for `dbSnapshot.provider`. Server-side resolver dispatches on this. */
+declare const SUPPORTED_PROVIDERS: readonly ["neon", "ardent", "dolt", "gfs", "mongodb-atlas", "dynamodb", "snowflake", "bigquery"];
+type DbSnapshotProvider = (typeof SUPPORTED_PROVIDERS)[number];
+interface DbSnapshotConfig {
+    /** Discriminator for the server-side resolver. */
+    provider: DbSnapshotProvider;
+}
+interface DbSnapshotRef {
+    provider: DbSnapshotProvider;
+    /**
+     * The wall-clock ISO timestamp the SDK observed immediately before
+     * invoking the wrapped function. This is the moment used as the
+     * "snapshot pin" by the timestamp-based resolver path. The name encodes
+     * its provenance: SDK-observed, wall clock (not monotonic), captured
+     * before user code began executing — distinct from server-side or
+     * DB-side timestamps recorded elsewhere on the trace.
+     */
+    sdkWallClockBeforeFn: string;
+    /**
+     * Reserved for future provider-specific opaque payload (e.g. customer
+     * LSN once a source-to-replica mapping exists). Unused in v0.
+     */
+    ref?: Record<string, unknown>;
+}
+
 /**
- * Error class for Bitfab API errors.
+ * Shared error type for Bitfab SDK runtime errors. Lives in its own
+ * module to avoid import cycles between `http.ts` and modules that need
+ * to throw structured errors (e.g. `dbSnapshot.ts` validation).
  */
 declare class BitfabError extends Error {
     readonly url?: string | undefined;
     constructor(message: string, url?: string | undefined);
 }
+
+/**
+ * HTTP client utilities for Bitfab API requests.
+ *
+ * This module provides:
+ * - HttpClient class for making API requests
+ * - awaitOnExit helper for fire-and-forget operations that must complete before process exit
+ */
+
 /**
  * Wait for all pending fire-and-forget operations (spans, traces) to complete.
  * Useful in tests and scripts to ensure all data has been sent before asserting or exiting.
@@ -249,6 +291,66 @@ declare class BitfabLangGraphCallbackHandler {
     handleRetrieverError(error: unknown, runId: string): Promise<void>;
 }
 
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+interface ReplayEnvironmentSnapshot {
+    databaseUrl: string;
+    expiresAt: string;
+    providerConsoleUrl?: string;
+    readOnly?: boolean;
+    traceId: string;
+    precision: "timestamp" | "lsn";
+}
+declare class ReplayEnvironment {
+    /**
+     * 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 historical trace ID that produced the input for this replay item. */
+    get traceId(): string;
+    /**
+     * How the resolver pinned this branch.
+     * - "timestamp": snapshot at SDK wall clock; bounded by replication lag.
+     * - "lsn": customer LSN mapped to a replica snapshot (future).
+     */
+    get precision(): "timestamp" | "lsn";
+    /** 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;
+    private read;
+    private require;
+}
+
 /**
  * Replay historical traces through a function and create a test run.
  *
@@ -285,6 +387,13 @@ interface ReplayOptions {
      * - "marked": only spans tagged with { mockOnReplay: true } in SpanOptions are mocked
      */
     mock?: MockStrategy;
+    /**
+     * 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.
+     */
+    environment?: ReplayEnvironment;
 }
 interface ReplayItem<T> {
     /** Deserialized inputs from the original trace. */
@@ -301,6 +410,13 @@ interface ReplayItem<T> {
     tokens: TokenUsage | null;
     /** Model name from the original trace, or null if not captured. */
     model: string | null;
+    /**
+     * The DB snapshot ref the SDK captured at trace open. Useful for debugging
+     * ("what state was this trace pinned to?") and for customers building
+     * their own resolvers. Undefined when the source trace was captured
+     * without `dbSnapshot` configured.
+     */
+    dbSnapshotRef: DbSnapshotRef | null;
 }
 
 interface ReplayResult<T> {
@@ -549,6 +665,13 @@ interface BitfabConfig {
     enabled?: boolean;
     /** The generated BAML client instance (e.g., `b` from your baml_client). Used by wrapBAML() when no explicit client is passed. */
     bamlClient?: unknown;
+    /**
+     * Per-trace database snapshot config. When set, every root span captures
+     * a wall-clock timestamp (and, if `captureRef` is provided, a provider-
+     * specific point-in-time ref) so the trace can later be replayed against
+     * a branch materialized from that point.
+     */
+    dbSnapshot?: DbSnapshotConfig;
 }
 /**
  * Span types matching the backend enum.
@@ -589,6 +712,12 @@ 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 apiKey;
     private readonly serviceUrl;
     private readonly timeout;
@@ -596,6 +725,7 @@ declare class Bitfab {
     private readonly enabled;
     private readonly httpClient;
     private readonly bamlClient;
+    private readonly dbSnapshot;
     /**
      * Initialize the Bitfab client.
      *
@@ -812,6 +942,7 @@ declare class Bitfab {
         codeChangeDescription?: string;
         codeChangeFiles?: CodeChangeFile[];
         mock?: "none" | "all" | "marked";
+        environment?: ReplayEnvironment;
     }): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -875,7 +1006,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.13.3";
+declare const __version__ = "0.13.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -885,4 +1016,4 @@ declare const __version__ = "0.13.3";
  */
 declare const DEFAULT_SERVICE_URL = "https://bitfab.ai";
 
-export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DetachedTrace, type MockStrategy, type ProviderDefinition, type ReplayItem, type ReplayOptions, type ReplayResult, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };
+export { type ActiveSpanContext, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, flushTraces, getCurrentSpan, getCurrentTrace };

package/dist/index.js

@@ -13,15 +13,17 @@ import {
   BitfabFunction,
   BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor,
+  ReplayEnvironment,
+  SUPPORTED_PROVIDERS,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-NHYPYRQB.js";
+} from "./chunk-XUW46356.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
   __version__,
   flushTraces
-} from "./chunk-LOZFAPCS.js";
+} from "./chunk-SKJWF5VX.js";
 export {
   Bitfab,
   BitfabClaudeAgentHandler,
@@ -30,6 +32,8 @@ export {
   BitfabLangGraphCallbackHandler,
   BitfabOpenAITracingProcessor,
   DEFAULT_SERVICE_URL,
+  ReplayEnvironment,
+  SUPPORTED_PROVIDERS,
   __version__,
   flushTraces,
   getCurrentSpan,