@bitfab/sdk 0.38.9 → 0.39.0

package/dist/index.d.cts

@@ -1288,6 +1288,13 @@ declare class BitfabOpenAIAgentHandler {
  */
 
 type MockStrategy = "none" | "all" | "marked";
+/**
+ * How a source trace came to exist. A `seeded` trace was written from a case
+ * with {@link Bitfab.seedTrace} rather than executed, so it has no recorded
+ * child spans to mock from and no database state to restore, and its recorded
+ * output is the value the case expected rather than a previous run's result.
+ */
+type TraceIngestionType = "captured" | "seeded";
 /**
  * How the DB-snapshot branch each replay item runs against is sized and warmed.
  *
@@ -1418,6 +1425,15 @@ interface ReplayOptions {
      * Omit it to spread the recorded inputs unchanged.
      */
     adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+    /**
+     * Resolve every item's inputs and stop, without calling the function.
+     *
+     * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
+     * item reports the exact arguments the function would have received. Nothing
+     * executes and no replay traces are produced, which is the cheap way to check
+     * that recorded inputs still fit the current signature.
+     */
+    dryRun?: boolean;
     /**
      * Called once per item as it finishes, in completion order (not input
      * order), with running totals for the whole run. Use it to render replay
@@ -1620,8 +1636,17 @@ interface ReplayItem<T> {
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
     result: T | undefined;
-    /** The original output from the historical trace. */
+    /**
+     * The original output from the historical trace. For a `seeded` source this
+     * is the value the case expected, not a previous run's result, so a
+     * difference means the code missed the expectation rather than drifted.
+     */
     originalOutput: unknown;
+    /**
+     * How the source trace came to exist. Absent on servers that predate the
+     * field, which only ever served captured traces.
+     */
+    ingestionType?: TraceIngestionType;
     /**
      * Backward-compatible message for either error kind. Prefer `traceError` and
      * `replayError` when callers need the original exception and its source.
@@ -2209,6 +2234,12 @@ interface TraceOptions {
     name?: string;
     /** Root span type. Descendants are always `function` spans. */
     type?: SpanType;
+    /**
+     * Default replay-mocking policy for automatically captured descendants.
+     * When true, those descendants are mocked by the default "marked" strategy
+     * unless a node explicitly sets `mockOnReplay: false`. Defaults to false.
+     */
+    mockOnReplayDefault?: boolean;
     /** Maximum number of recorded descendant levels. Defaults to 30. */
     maxDepth?: number;
     /** Maximum descendant spans recorded per root invocation. Defaults to 500. */
@@ -2710,6 +2741,45 @@ declare class Bitfab {
     registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
     /** Remove all overrides registered via {@link registerMockOverride}. */
     clearMockOverrides(): void;
+    /**
+     * Write a replayable trace from a case, without running anything.
+     *
+     * Use this to turn a corpus you already hold (a Braintrust dataset, a
+     * spreadsheet, hand-written cases) into traces that {@link replay} can
+     * select. The recorded root span carries `input` as its input and `expected`
+     * as its output, so replay reports each item against the value you expected
+     * rather than against a previous run.
+     *
+     * A seeded trace has no child spans and no database pin, so replay mocking
+     * has nothing recorded to substitute and `dbBranch` refuses it. Pass
+     * `mockOverride` at replay time for calls that must not run.
+     *
+     * @returns The trace ID, usable with `replay({ traceIds: [...] })`.
+     */
+    seedTrace(traceFunctionKey: string, options: {
+        /** Arguments spread into the function at replay, as `fn(...input)`. */
+        input: unknown[];
+        /**
+         * The output this case should produce. Optional, but without it the
+         * replay has nothing to be judged against.
+         */
+        expected?: unknown;
+        /**
+         * The function these inputs will replay through. When given, the call is
+         * checked against its arity here, so a case that cannot supply the
+         * function's required arguments fails now instead of at replay. Omit it
+         * when the seeding script cannot import the function.
+         */
+        fn?: (...args: any[]) => unknown;
+        /**
+         * Recorded on the trace. Put the source row's id here so a seeded trace
+         * can be traced back to the case it came from.
+         */
+        metadata?: Record<string, unknown>;
+        sessionId?: string;
+        spanName?: string;
+        spanType?: SpanType;
+    }): string;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -2885,7 +2955,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.9";
+declare const __version__ = "0.39.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2987,5 +3057,30 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  * SDK upgrade can add replay features without regenerating the project file.
  */
 declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+/** One case to seed, in the shape `--seed` reads from JSON or JSONL. */
+interface SeedCase {
+    /** Arguments spread into the registered function at replay. */
+    input: unknown[];
+    /** The output this case should produce. */
+    expected?: unknown;
+    /** Recorded on the trace, for tracing a seeded case back to its source row. */
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+}
+interface SeedResult {
+    pipeline: string;
+    traceFunctionKey: string;
+    traceIds: string[];
+}
+/**
+ * Seed cases through an already-registered pipeline.
+ *
+ * The registration is the whole point: it already holds the client, the exact
+ * function production calls, and the trace function key replay selects by, so
+ * a seeded case is guaranteed to line up with the replay that will read it.
+ * Passing the registered function to `seedTrace` also means a case that cannot
+ * supply its required arguments is rejected here rather than at replay.
+ */
+declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, cases: readonly SeedCase[]): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, 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 LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, 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__, defineReplayRegistry, 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, BitfabLangGraphIntegration, 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 LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SeedCase, type SeedResult, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };

package/dist/index.d.ts

@@ -1288,6 +1288,13 @@ declare class BitfabOpenAIAgentHandler {
  */
 
 type MockStrategy = "none" | "all" | "marked";
+/**
+ * How a source trace came to exist. A `seeded` trace was written from a case
+ * with {@link Bitfab.seedTrace} rather than executed, so it has no recorded
+ * child spans to mock from and no database state to restore, and its recorded
+ * output is the value the case expected rather than a previous run's result.
+ */
+type TraceIngestionType = "captured" | "seeded";
 /**
  * How the DB-snapshot branch each replay item runs against is sized and warmed.
  *
@@ -1418,6 +1425,15 @@ interface ReplayOptions {
      * Omit it to spread the recorded inputs unchanged.
      */
     adaptInputs?: (inputs: unknown[], ctx: AdaptContext) => unknown[];
+    /**
+     * Resolve every item's inputs and stop, without calling the function.
+     *
+     * Selection, span fetch, deserialization, and `adaptInputs` all run, so each
+     * item reports the exact arguments the function would have received. Nothing
+     * executes and no replay traces are produced, which is the cheap way to check
+     * that recorded inputs still fit the current signature.
+     */
+    dryRun?: boolean;
     /**
      * Called once per item as it finishes, in completion order (not input
      * order), with running totals for the whole run. Use it to render replay
@@ -1620,8 +1636,17 @@ interface ReplayItem<T> {
     input: unknown[];
     /** The result returned by the function during replay, or undefined on error. */
     result: T | undefined;
-    /** The original output from the historical trace. */
+    /**
+     * The original output from the historical trace. For a `seeded` source this
+     * is the value the case expected, not a previous run's result, so a
+     * difference means the code missed the expectation rather than drifted.
+     */
     originalOutput: unknown;
+    /**
+     * How the source trace came to exist. Absent on servers that predate the
+     * field, which only ever served captured traces.
+     */
+    ingestionType?: TraceIngestionType;
     /**
      * Backward-compatible message for either error kind. Prefer `traceError` and
      * `replayError` when callers need the original exception and its source.
@@ -2209,6 +2234,12 @@ interface TraceOptions {
     name?: string;
     /** Root span type. Descendants are always `function` spans. */
     type?: SpanType;
+    /**
+     * Default replay-mocking policy for automatically captured descendants.
+     * When true, those descendants are mocked by the default "marked" strategy
+     * unless a node explicitly sets `mockOnReplay: false`. Defaults to false.
+     */
+    mockOnReplayDefault?: boolean;
     /** Maximum number of recorded descendant levels. Defaults to 30. */
     maxDepth?: number;
     /** Maximum descendant spans recorded per root invocation. Defaults to 500. */
@@ -2710,6 +2741,45 @@ declare class Bitfab {
     registerMockOverride(traceFunctionKey: string, override: MockOverride | MockOverrideResolver): void;
     /** Remove all overrides registered via {@link registerMockOverride}. */
     clearMockOverrides(): void;
+    /**
+     * Write a replayable trace from a case, without running anything.
+     *
+     * Use this to turn a corpus you already hold (a Braintrust dataset, a
+     * spreadsheet, hand-written cases) into traces that {@link replay} can
+     * select. The recorded root span carries `input` as its input and `expected`
+     * as its output, so replay reports each item against the value you expected
+     * rather than against a previous run.
+     *
+     * A seeded trace has no child spans and no database pin, so replay mocking
+     * has nothing recorded to substitute and `dbBranch` refuses it. Pass
+     * `mockOverride` at replay time for calls that must not run.
+     *
+     * @returns The trace ID, usable with `replay({ traceIds: [...] })`.
+     */
+    seedTrace(traceFunctionKey: string, options: {
+        /** Arguments spread into the function at replay, as `fn(...input)`. */
+        input: unknown[];
+        /**
+         * The output this case should produce. Optional, but without it the
+         * replay has nothing to be judged against.
+         */
+        expected?: unknown;
+        /**
+         * The function these inputs will replay through. When given, the call is
+         * checked against its arity here, so a case that cannot supply the
+         * function's required arguments fails now instead of at replay. Omit it
+         * when the seeding script cannot import the function.
+         */
+        fn?: (...args: any[]) => unknown;
+        /**
+         * Recorded on the trace. Put the source row's id here so a seeded trace
+         * can be traced back to the case it came from.
+         */
+        metadata?: Record<string, unknown>;
+        sessionId?: string;
+        spanName?: string;
+        spanType?: SpanType;
+    }): string;
     replay<TReturn>(traceFunctionKey: string, fn: (...args: any[]) => TReturn | Promise<TReturn>, options?: ReplayOptions): Promise<ReplayResult<TReturn>>;
 }
 /**
@@ -2885,7 +2955,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.9";
+declare const __version__ = "0.39.0";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2987,5 +3057,30 @@ type ReplayRegistry = Record<string, ReplayRegistration>;
  * SDK upgrade can add replay features without regenerating the project file.
  */
 declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+/** One case to seed, in the shape `--seed` reads from JSON or JSONL. */
+interface SeedCase {
+    /** Arguments spread into the registered function at replay. */
+    input: unknown[];
+    /** The output this case should produce. */
+    expected?: unknown;
+    /** Recorded on the trace, for tracing a seeded case back to its source row. */
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+}
+interface SeedResult {
+    pipeline: string;
+    traceFunctionKey: string;
+    traceIds: string[];
+}
+/**
+ * Seed cases through an already-registered pipeline.
+ *
+ * The registration is the whole point: it already holds the client, the exact
+ * function production calls, and the trace function key replay selects by, so
+ * a seeded case is guaranteed to line up with the replay that will read it.
+ * Passing the registered function to `seedTrace` also means a case that cannot
+ * supply its required arguments is rejected here rather than at replay.
+ */
+declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, cases: readonly SeedCase[]): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, 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 LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, 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__, defineReplayRegistry, 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, BitfabLangGraphIntegration, 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 LangGraphIntegrationOptions, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SeedCase, type SeedResult, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceIngestionType, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult };

package/dist/index.js

@@ -12,22 +12,25 @@ import {
   finalizers,
   getCurrentReplayBranch,
   getCurrentSpan,
-  getCurrentTrace
-} from "./chunk-B4XXAK74.js";
+  getCurrentTrace,
+  seedFromRegistry
+} from "./chunk-SHJ3ABUG.js";
 import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
-  BitfabError,
-  DEFAULT_SERVICE_URL,
   DbBranchReplayError,
-  HttpClient,
   NO_MOCK_OVERRIDE,
   ReplayError,
-  __version__,
-  flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-2I5TFNGK.js";
+} from "./chunk-FW7PZ3EP.js";
+import {
+  BitfabError,
+  DEFAULT_SERVICE_URL,
+  HttpClient,
+  __version__,
+  flushTraces
+} from "./chunk-2JQSYJJR.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -55,6 +58,7 @@ export {
   getCurrentSpan,
   getCurrentTrace,
   reportReplayProgress,
+  seedFromRegistry,
   serializeReplayResult
 };
 //# sourceMappingURL=index.js.map

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.38.9";
+    __version__ = "0.39.0";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -1205,6 +1205,16 @@ var init_transport = __esm({
 });
 
 // src/http.ts
+var http_exports = {};
+__export(http_exports, {
+  BitfabError: () => BitfabError,
+  HttpClient: () => HttpClient,
+  awaitOnExit: () => awaitOnExit,
+  awaitPendingRequests: () => awaitPendingRequests,
+  flushTraces: () => flushTraces,
+  parseRetryAfterMs: () => parseRetryAfterMs,
+  serializePayloadBody: () => serializePayloadBody
+});
 function awaitOnExit(promise) {
   pendingTracePromises.add(promise);
   void promise.finally(() => {
@@ -2549,7 +2559,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, includeDbBranchLease, dbBranchSettings, adaptInputs) {
+async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy, resolvedOverrides, replayedTraceId, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
   let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
   let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
   let dbSnapshotRef = serverItem.dbSnapshotRef;
@@ -2644,6 +2654,32 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
       }
       return pending;
     } : void 0;
+    if (dryRun) {
+      return {
+        traceId: null,
+        originalTraceId,
+        originalSpanId,
+        sourceTraceId: originalTraceId,
+        sourceSpanId: originalSpanId,
+        input: inputs,
+        result: void 0,
+        originalOutput,
+        ...serverItem.ingestionType && {
+          ingestionType: serverItem.ingestionType
+        },
+        error: null,
+        traceError: null,
+        replayError: null,
+        durationMs: null,
+        originalDurationMs: serverItem.originalDurationMs ?? serverItem.durationMs ?? null,
+        originalTokens: serverItem.originalTokens ?? serverItem.tokens ?? null,
+        originalModel: serverItem.originalModel ?? serverItem.model ?? null,
+        tokens: null,
+        model: serverItem.originalModel ?? serverItem.model ?? null,
+        dbSnapshotRef: dbSnapshotRef ?? null,
+        dbBranchTimings: dbBranchTimings ?? null
+      };
+    }
     try {
       replayStarted = performance.now();
       const maybePromise = runWithReplayContext(
@@ -2707,6 +2743,9 @@ async function processItem(httpClient, serverItem, fn, testRunId, mockStrategy,
     input: inputs,
     result,
     originalOutput,
+    ...serverItem.ingestionType && {
+      ingestionType: serverItem.ingestionType
+    },
     error,
     traceError,
     replayError,
@@ -2854,13 +2893,23 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     options?.name,
     codeChangeDescription,
     codeChangeFiles,
-    dbBranchEnabled(options?.dbBranch),
-    // includeDbBranchLease
+    // A dry run executes nothing, so a branch would be provisioned (and billed)
+    // for code that never runs, and a seeded source's refusal would fail the item
+    // before it could report its resolved inputs.
+    dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
     options?.experimentGroupId,
     options?.datasetId,
     options?.graderIds,
     resolveDbBranchSettings(options?.dbBranch)
   );
+  if (serverItems.length === 0) {
+    try {
+      console.warn(
+        `Bitfab: no traces matched "${traceFunctionKey}", so this replay ran nothing. Capture a trace, or seed one with seedTrace, before replaying.`
+      );
+    } catch {
+    }
+  }
   const mockStrategy = options?.mock ?? "marked";
   const maxConcurrency = options?.maxConcurrency ?? 10;
   const fullTestRunUrl = `${serviceUrl}${testRunUrl}`;
@@ -2879,9 +2928,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       mockStrategy,
       resolvedOverrides,
       replayedTraceIds[index],
-      dbBranchEnabled(options?.dbBranch),
+      dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
       resolveDbBranchSettings(options?.dbBranch),
-      options?.adaptInputs
+      options?.adaptInputs,
+      options?.dryRun === true
     )
   );
   const total = tasks.length;
@@ -2989,6 +3039,16 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     } : void 0
   );
+  if (options?.dryRun === true) {
+    await httpClient.completeReplay(testRunId).catch(() => void 0);
+    const dryResult = {
+      items: resultItems,
+      testRunId,
+      testRunUrl: fullTestRunUrl
+    };
+    await writeReplayResultFile(dryResult);
+    return dryResult;
+  }
   const deliveredTraceIds = await preserveReplayFailure(
     () => waitForReplayPersistence(httpClient, testRunId, replayedTraceIds),
     resultItems,
@@ -3157,6 +3217,7 @@ __export(node_exports, {
   getCurrentSpan: () => getCurrentSpan,
   getCurrentTrace: () => getCurrentTrace,
   reportReplayProgress: () => reportReplayProgress,
+  seedFromRegistry: () => seedFromRegistry,
   serializeReplayResult: () => serializeReplayResult
 });
 module.exports = __toCommonJS(node_exports);
@@ -6176,6 +6237,7 @@ var Bitfab = class {
               return invokeWithoutNode();
             }
             spansUsed += 1;
+            const mockOnReplay = nodeConfiguration?.mockOnReplay ?? options.mockOnReplayDefault;
             const childOptions = {
               name: nodeConfiguration?.name ?? definition.name,
               type: nodeConfiguration?.type ?? "function",
@@ -6186,8 +6248,8 @@ var Bitfab = class {
               ...nodeConfiguration?.testRunId !== void 0 && {
                 testRunId: nodeConfiguration.testRunId
               },
-              ...nodeConfiguration?.mockOnReplay !== void 0 && {
-                mockOnReplay: nodeConfiguration.mockOnReplay
+              ...mockOnReplay !== void 0 && {
+                mockOnReplay
               },
               ...nodeConfiguration?.finalize !== void 0 && {
                 finalize: nodeConfiguration.finalize
@@ -6873,6 +6935,7 @@ var Bitfab = class {
                 inputSourceTraceId: traceState?.inputSourceTraceId,
                 dbSnapshotRef: traceState?.dbSnapshotRef,
                 dropped: traceState?.dropped,
+                ingestionType: traceState?.ingestionType,
                 // Built AFTER the wrapped fn finished, so `accessed` reflects
                 // whether customer code obtained the branch URL during this
                 // item. Omitted entirely when no lease was attached, so the
@@ -7096,6 +7159,7 @@ var Bitfab = class {
     Object.defineProperty(wrappedFn, "_bitfabTraceFunctionKey", {
       value: traceFunctionKey
     });
+    Object.defineProperty(wrappedFn, "_bitfabWrappedFn", { value: fn });
     return wrappedFn;
   }
   /**
@@ -7258,6 +7322,9 @@ var Bitfab = class {
     if (params.dbSnapshotRef) {
       rawTrace.db_snapshot_ref = params.dbSnapshotRef;
     }
+    if (params.ingestionType) {
+      rawTrace.ingestion_type = params.ingestionType;
+    }
     if (params.dbSnapshotUsage) {
       rawTrace.db_snapshot_usage = {
         neon_branch_id: params.dbSnapshotUsage.neonBranchId,
@@ -7404,6 +7471,68 @@ var Bitfab = class {
   clearMockOverrides() {
     this.mockOverrides.length = 0;
   }
+  /**
+   * Write a replayable trace from a case, without running anything.
+   *
+   * Use this to turn a corpus you already hold (a Braintrust dataset, a
+   * spreadsheet, hand-written cases) into traces that {@link replay} can
+   * select. The recorded root span carries `input` as its input and `expected`
+   * as its output, so replay reports each item against the value you expected
+   * rather than against a previous run.
+   *
+   * A seeded trace has no child spans and no database pin, so replay mocking
+   * has nothing recorded to substitute and `dbBranch` refuses it. Pass
+   * `mockOverride` at replay time for calls that must not run.
+   *
+   * @returns The trace ID, usable with `replay({ traceIds: [...] })`.
+   */
+  seedTrace(traceFunctionKey, options) {
+    const { input } = options;
+    const fn = options.fn?._bitfabWrappedFn ?? options.fn;
+    if (fn && input.length < fn.length) {
+      throw new BitfabError(
+        `Seeded case supplies ${input.length} argument(s) but ${fn.name === "" ? "the function" : fn.name} requires ${fn.length}. Fix the case, or omit fn to seed it anyway.`
+      );
+    }
+    const traceId = randomUuid();
+    const startedAt = nowIsoTimestamp();
+    activeTraceStates.set(traceId, {
+      traceId,
+      startedAt,
+      contexts: [],
+      ingestionType: "seeded",
+      ...options.sessionId !== void 0 && { sessionId: options.sessionId },
+      ...options.metadata !== void 0 && { metadata: options.metadata }
+    });
+    try {
+      this.sendWrapperSpan({
+        traceFunctionKey,
+        spanName: options.spanName ?? traceFunctionKey,
+        traceId,
+        spanId: randomUuid(),
+        parentSpanId: null,
+        inputs: input,
+        result: options.expected,
+        startedAt,
+        endedAt: startedAt,
+        spanType: options.spanType ?? "agent",
+        captureContent: true
+      });
+      this.sendTraceCompletion({
+        traceFunctionKey,
+        traceId,
+        startedAt,
+        endedAt: startedAt,
+        sessionId: options.sessionId,
+        metadata: options.metadata,
+        contexts: [],
+        ingestionType: "seeded"
+      });
+    } finally {
+      activeTraceStates.delete(traceId);
+    }
+    return traceId;
+  }
   async replay(traceFunctionKey, fn, options) {
     const wrappedKey = fn._bitfabTraceFunctionKey;
     let replayFn = fn;
@@ -7664,6 +7793,37 @@ init_replay();
 function defineReplayRegistry(registry) {
   return registry;
 }
+async function seedFromRegistry(registry, pipeline, cases) {
+  const registration = registry[pipeline];
+  if (registration === void 0) {
+    throw new BitfabError(
+      `Unknown pipeline '${pipeline}'. Registered: ${Object.keys(registry).join(", ")}`
+    );
+  }
+  const traceFunctionKey = resolveTraceFunctionKey(registration);
+  const traceIds = cases.map(
+    (seedCase) => registration.client.seedTrace(traceFunctionKey, {
+      input: seedCase.input,
+      expected: seedCase.expected,
+      fn: registration.fn,
+      metadata: seedCase.metadata,
+      sessionId: seedCase.sessionId
+    })
+  );
+  const { flushTraces: flushTraces2 } = await Promise.resolve().then(() => (init_http(), http_exports));
+  await flushTraces2(3e4);
+  return { pipeline, traceFunctionKey, traceIds };
+}
+function resolveTraceFunctionKey(registration) {
+  const wrappedKey = registration.fn._bitfabTraceFunctionKey;
+  const key = registration.traceFunctionKey ?? wrappedKey;
+  if (key === void 0) {
+    throw new BitfabError(
+      "Replay registry entry uses a plain function. Set traceFunctionKey to the key its production handler records."
+    );
+  }
+  return key;
+}
 
 // src/node.ts
 init_asyncStorage();
@@ -7695,6 +7855,7 @@ assertAsyncStorageRegistered();
   getCurrentSpan,
   getCurrentTrace,
   reportReplayProgress,
+  seedFromRegistry,
   serializeReplayResult
 });
 //# sourceMappingURL=node.cjs.map