@bitfab/sdk 0.38.9 → 0.39.0

package/dist/node.d.cts

@@ -1 +1 @@
-export { ActiveSpanContext, AdaptContext, AdaptInputsFn, AllowedEnvVars, BITFAB_PROGRESS_PREFIX, BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, BitfabConfig, BitfabError, BitfabFunction, BitfabLangChainCallbackHandler, BitfabLangChainCallbackHandler as BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, LangGraphIntegrationOptions, MockOverride, MockOverrideCtx, MockOverrideInput, MockOverrideResolver, MockStrategy, MockValue, NO_MOCK_OVERRIDE, NodeMatcher, NodeMethodDecorator, NodeOptions, ProviderDefinition, ReplayBranch, ReplayError, ReplayItem, ReplayItemFinishProgress, ReplayItemStartProgress, ReplayOptions, ReplayOptionsFactory, ReplayProgress, ReplayProgressItem, ReplayRegistration, ReplayRegistry, ReplayRegistryContext, ReplayRegistryOptions, ReplayResult, SUPPORTED_PROVIDERS, SpanLookup, SpanMethodDecorator, SpanMethodDecoratorContext, SpanNodeMeta, SpanOccurrence, SpanOptions, SpanType, TokenUsage, TraceResponse, TracingProcessor, VercelCallParams, VercelGenerateResult, VercelStreamResult, WrapBAMLOptions, WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult } from './index.cjs';
+export { ActiveSpanContext, AdaptContext, AdaptInputsFn, AllowedEnvVars, BITFAB_PROGRESS_PREFIX, BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, BitfabConfig, BitfabError, BitfabFunction, BitfabLangChainCallbackHandler, BitfabLangChainCallbackHandler as BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, LangGraphIntegrationOptions, MockOverride, MockOverrideCtx, MockOverrideInput, MockOverrideResolver, MockStrategy, MockValue, NO_MOCK_OVERRIDE, NodeMatcher, NodeMethodDecorator, NodeOptions, ProviderDefinition, ReplayBranch, ReplayError, ReplayItem, ReplayItemFinishProgress, ReplayItemStartProgress, ReplayOptions, ReplayOptionsFactory, ReplayProgress, ReplayProgressItem, ReplayRegistration, ReplayRegistry, ReplayRegistryContext, ReplayRegistryOptions, ReplayResult, SUPPORTED_PROVIDERS, SeedCase, SeedResult, SpanLookup, SpanMethodDecorator, SpanMethodDecoratorContext, SpanNodeMeta, SpanOccurrence, SpanOptions, SpanType, TokenUsage, TraceIngestionType, TraceResponse, TracingProcessor, VercelCallParams, VercelGenerateResult, VercelStreamResult, WrapBAMLOptions, WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult } from './index.cjs';

package/dist/node.d.ts

@@ -1 +1 @@
-export { ActiveSpanContext, AdaptContext, AdaptInputsFn, AllowedEnvVars, BITFAB_PROGRESS_PREFIX, BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, BitfabConfig, BitfabError, BitfabFunction, BitfabLangChainCallbackHandler, BitfabLangChainCallbackHandler as BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, LangGraphIntegrationOptions, MockOverride, MockOverrideCtx, MockOverrideInput, MockOverrideResolver, MockStrategy, MockValue, NO_MOCK_OVERRIDE, NodeMatcher, NodeMethodDecorator, NodeOptions, ProviderDefinition, ReplayBranch, ReplayError, ReplayItem, ReplayItemFinishProgress, ReplayItemStartProgress, ReplayOptions, ReplayOptionsFactory, ReplayProgress, ReplayProgressItem, ReplayRegistration, ReplayRegistry, ReplayRegistryContext, ReplayRegistryOptions, ReplayResult, SUPPORTED_PROVIDERS, SpanLookup, SpanMethodDecorator, SpanMethodDecoratorContext, SpanNodeMeta, SpanOccurrence, SpanOptions, SpanType, TokenUsage, TraceResponse, TracingProcessor, VercelCallParams, VercelGenerateResult, VercelStreamResult, WrapBAMLOptions, WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult } from './index.js';
+export { ActiveSpanContext, AdaptContext, AdaptInputsFn, AllowedEnvVars, BITFAB_PROGRESS_PREFIX, BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, BitfabConfig, BitfabError, BitfabFunction, BitfabLangChainCallbackHandler, BitfabLangChainCallbackHandler as BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, LangGraphIntegrationOptions, MockOverride, MockOverrideCtx, MockOverrideInput, MockOverrideResolver, MockStrategy, MockValue, NO_MOCK_OVERRIDE, NodeMatcher, NodeMethodDecorator, NodeOptions, ProviderDefinition, ReplayBranch, ReplayError, ReplayItem, ReplayItemFinishProgress, ReplayItemStartProgress, ReplayOptions, ReplayOptionsFactory, ReplayProgress, ReplayProgressItem, ReplayRegistration, ReplayRegistry, ReplayRegistryContext, ReplayRegistryOptions, ReplayResult, SUPPORTED_PROVIDERS, SeedCase, SeedResult, SpanLookup, SpanMethodDecorator, SpanMethodDecoratorContext, SpanNodeMeta, SpanOccurrence, SpanOptions, SpanType, TokenUsage, TraceIngestionType, TraceResponse, TracingProcessor, VercelCallParams, VercelGenerateResult, VercelStreamResult, WrapBAMLOptions, WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, seedFromRegistry, serializeReplayResult } from './index.js';

package/dist/node.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 {
   assertAsyncStorageRegistered,
   registerAsyncLocalStorageClass
@@ -67,6 +70,7 @@ export {
   getCurrentSpan,
   getCurrentTrace,
   reportReplayProgress,
+  seedFromRegistry,
   serializeReplayResult
 };
 //# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/asyncStorageNode.ts","../src/node.ts"],"sourcesContent":["/**\n * Synchronous AsyncLocalStorage registration for Node.js.\n *\n * This module is a side-effect-only import: it registers the Node.js\n * AsyncLocalStorage class into the shared registry so span nesting\n * works immediately - no async gap, no microtask delay.\n *\n * It is imported by `node.ts` (the Node.js-specific entry point) as\n * the FIRST import, before `index.ts` or `client.ts` are evaluated.\n *\n * This file must ONLY be imported in Node.js environments (not browsers).\n * It uses a static `import` of `node:async_hooks`, which will fail in\n * browser bundlers. The `node.ts` entry point is conditionally selected\n * via package.json `exports` conditions, so browsers never see this file.\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\"\nimport type { AsyncLocalStorageLike } from \"./asyncStorage.js\"\nimport { registerAsyncLocalStorageClass } from \"./asyncStorage.js\"\n\nregisterAsyncLocalStorageClass(\n  AsyncLocalStorage as unknown as new () => AsyncLocalStorageLike<unknown>,\n)\n","/**\n * Node.js-specific entry point for the Bitfab SDK.\n *\n * Selected automatically via package.json `exports` conditions when the\n * consumer's runtime or bundler supports the \"node\" condition (Node.js,\n * most server-side bundlers).\n *\n * This entry point differs from the default (`index.ts`) in one way:\n * it synchronously registers Node.js's `AsyncLocalStorage` before any\n * other SDK code evaluates. This eliminates the async initialization\n * gap that the default entry point has (where the first span might\n * execute before the dynamic import of `node:async_hooks` resolves).\n *\n * The default entry point (`index.ts`) is used for browsers and other\n * environments where `node:async_hooks` is unavailable. There, span\n * nesting degrades gracefully to a shared stack (correct for sequential\n * async, but not for concurrent Promise.all patterns).\n */\n\n// ⚠️ IMPORT ORDER MATTERS\n// asyncStorageNode MUST be imported before index.js.\n// It registers the AsyncLocalStorage class synchronously during module\n// evaluation. index.js (via client.ts) reads from that registration at\n// span creation time. If this import is moved after index.js or removed,\n// span nesting silently degrades to the browser fallback (flat spans).\nimport \"./asyncStorageNode.js\"\n\nexport * from \"./index.js\"\n\n// Verify registration succeeded. This turns a silent degradation into a\n// loud error if someone reorders the imports above or if asyncStorageNode.ts\n// fails to register for any reason. Only runs in the Node.js entry point\n// where we know node:async_hooks must be available.\nimport { assertAsyncStorageRegistered } from \"./asyncStorage.js\"\n\nassertAsyncStorageRegistered()\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgBA,SAAS,yBAAyB;AAIlC;AAAA,EACE;AACF;;;ACaA,6BAA6B;","names":[]}
+{"version":3,"sources":["../src/asyncStorageNode.ts","../src/node.ts"],"sourcesContent":["/**\n * Synchronous AsyncLocalStorage registration for Node.js.\n *\n * This module is a side-effect-only import: it registers the Node.js\n * AsyncLocalStorage class into the shared registry so span nesting\n * works immediately - no async gap, no microtask delay.\n *\n * It is imported by `node.ts` (the Node.js-specific entry point) as\n * the FIRST import, before `index.ts` or `client.ts` are evaluated.\n *\n * This file must ONLY be imported in Node.js environments (not browsers).\n * It uses a static `import` of `node:async_hooks`, which will fail in\n * browser bundlers. The `node.ts` entry point is conditionally selected\n * via package.json `exports` conditions, so browsers never see this file.\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\"\nimport type { AsyncLocalStorageLike } from \"./asyncStorage.js\"\nimport { registerAsyncLocalStorageClass } from \"./asyncStorage.js\"\n\nregisterAsyncLocalStorageClass(\n  AsyncLocalStorage as unknown as new () => AsyncLocalStorageLike<unknown>,\n)\n","/**\n * Node.js-specific entry point for the Bitfab SDK.\n *\n * Selected automatically via package.json `exports` conditions when the\n * consumer's runtime or bundler supports the \"node\" condition (Node.js,\n * most server-side bundlers).\n *\n * This entry point differs from the default (`index.ts`) in one way:\n * it synchronously registers Node.js's `AsyncLocalStorage` before any\n * other SDK code evaluates. This eliminates the async initialization\n * gap that the default entry point has (where the first span might\n * execute before the dynamic import of `node:async_hooks` resolves).\n *\n * The default entry point (`index.ts`) is used for browsers and other\n * environments where `node:async_hooks` is unavailable. There, span\n * nesting degrades gracefully to a shared stack (correct for sequential\n * async, but not for concurrent Promise.all patterns).\n */\n\n// ⚠️ IMPORT ORDER MATTERS\n// asyncStorageNode MUST be imported before index.js.\n// It registers the AsyncLocalStorage class synchronously during module\n// evaluation. index.js (via client.ts) reads from that registration at\n// span creation time. If this import is moved after index.js or removed,\n// span nesting silently degrades to the browser fallback (flat spans).\nimport \"./asyncStorageNode.js\"\n\nexport * from \"./index.js\"\n\n// Verify registration succeeded. This turns a silent degradation into a\n// loud error if someone reorders the imports above or if asyncStorageNode.ts\n// fails to register for any reason. Only runs in the Node.js entry point\n// where we know node:async_hooks must be available.\nimport { assertAsyncStorageRegistered } from \"./asyncStorage.js\"\n\nassertAsyncStorageRegistered()\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgBA,SAAS,yBAAyB;AAIlC;AAAA,EACE;AACF;;;ACaA,6BAA6B;","names":[]}

package/dist/{replay-EC7CQOO3.js → replay-MZYX4IFV.js}

@@ -7,7 +7,8 @@ import {
   serializeReplayResult,
   sleepForReplayPersistence,
   waitForReplayPersistence
-} from "./chunk-2I5TFNGK.js";
+} from "./chunk-FW7PZ3EP.js";
+import "./chunk-2JQSYJJR.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -19,4 +20,4 @@ export {
   sleepForReplayPersistence,
   waitForReplayPersistence
 };
-//# sourceMappingURL=replay-EC7CQOO3.js.map
+//# sourceMappingURL=replay-MZYX4IFV.js.map

package/dist/replay-MZYX4IFV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/replayCli.js

@@ -1,150 +1,14 @@
 #!/usr/bin/env node
+import {
+  BitfabError
+} from "./chunk-RH4K4RSS.js";
 
 // src/replayCli.ts
 import { tsImport } from "tsx/esm/api";
 
-// src/errors.ts
-var BitfabError = class extends Error {
-  constructor(message, url, status, retryAfterMs) {
-    super(message);
-    this.url = url;
-    this.status = status;
-    this.retryAfterMs = retryAfterMs;
-    this.name = "BitfabError";
-  }
-};
-
 // src/codeChange.ts
 var NUL = String.fromCharCode(0);
 
-// src/compress.ts
-var gzipNode;
-var _nodeGzipReady = (typeof process !== "undefined" && process.versions?.node ? (
-  // The join trick hides "node:zlib" from static analysis so bundlers that
-  // ban Node.js built-ins don't fail at build time. webpackIgnore tells
-  // webpack/turbopack to emit a native import() so Node.js can resolve the
-  // module at runtime. Same pattern as `asyncStorage.ts`.
-  import(
-    /* webpackIgnore: true */
-    ["node", "zlib"].join(":")
-  ).then(({ gzip }) => {
-    gzipNode = (data) => new Promise((resolve, reject) => {
-      gzip(data, (error, result) => {
-        if (error) {
-          reject(error);
-        } else {
-          resolve(result);
-        }
-      });
-    });
-  }).catch(() => {
-  })
-) : Promise.resolve()).then(() => {
-});
-
-// src/asyncStorage.ts
-var AsyncLocalStorageClass = null;
-var initDone = false;
-function registerAsyncLocalStorageClass(cls) {
-  if (!AsyncLocalStorageClass) {
-    AsyncLocalStorageClass = cls;
-  }
-  initDone = true;
-}
-var asyncStorageReady = (typeof process !== "undefined" && process.versions?.node ? (
-  // The join trick hides "node:async_hooks" from static analysis so
-  // bundlers that ban Node.js built-ins don't fail at build time.
-  // webpackIgnore tells webpack/turbopack to emit a native import()
-  // so Node.js can resolve the module at runtime.
-  import(
-    /* webpackIgnore: true */
-    ["node", "async_hooks"].join(":")
-  ).then(
-    (mod) => {
-      registerAsyncLocalStorageClass(mod.AsyncLocalStorage);
-    }
-  ).catch(() => {
-  })
-) : Promise.resolve()).then(() => {
-  initDone = true;
-});
-function createAsyncLocalStorage() {
-  return AsyncLocalStorageClass ? new AsyncLocalStorageClass() : null;
-}
-
-// src/replayContext.ts
-var replayContextStorage = null;
-var REPLAY_CONTEXT_STORAGE_SYMBOL = /* @__PURE__ */ Symbol.for("bitfab.replayContextStorage");
-var replayContextReady = asyncStorageReady.then(() => {
-  const shared = globalThis;
-  const existing = shared[REPLAY_CONTEXT_STORAGE_SYMBOL];
-  if (existing) {
-    replayContextStorage = existing;
-    return;
-  }
-  const created = createAsyncLocalStorage();
-  if (created) {
-    shared[REPLAY_CONTEXT_STORAGE_SYMBOL] = created;
-    replayContextStorage = created;
-  }
-});
-
-// src/payloadBudget.ts
-var textEncoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
-
-// src/otel.ts
-import { SpanStatusCode } from "@opentelemetry/api";
-import {
-  ExportResultCode
-} from "@opentelemetry/core";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import {
-  AlwaysOnSampler,
-  BasicTracerProvider,
-  BatchSpanProcessor
-} from "@opentelemetry/sdk-trace-base";
-var DEFAULT_LIFECYCLE_TIMEOUT_MS = 3e4;
-var liveTransports = /* @__PURE__ */ new Set();
-async function forEachLiveTransport(timeoutMs, run) {
-  const deadline = Date.now() + Math.max(timeoutMs, 0);
-  let succeeded = true;
-  for (const transport of [...liveTransports]) {
-    succeeded = await run(transport, Math.max(0, deadline - Date.now())) && succeeded;
-  }
-  return succeeded;
-}
-function shutdownOtelTransports(timeoutMs = DEFAULT_LIFECYCLE_TIMEOUT_MS) {
-  return forEachLiveTransport(
-    timeoutMs,
-    (transport, remaining) => transport.shutdown(remaining)
-  );
-}
-
-// src/transport.ts
-function shutdownTraceTransports(timeoutMs) {
-  return shutdownOtelTransports(timeoutMs);
-}
-
-// src/http.ts
-var EXIT_FLUSH_TIMEOUT_MS = 5e3;
-var pendingTracePromises = /* @__PURE__ */ new Set();
-if (typeof process !== "undefined" && process.versions != null && process.versions.node != null) {
-  let isFlushing = false;
-  process.on("beforeExit", () => {
-    if (isFlushing) {
-      return;
-    }
-    isFlushing = true;
-    void Promise.allSettled([
-      ...Array.from(pendingTracePromises).map((p) => p.catch(() => {
-      })),
-      shutdownTraceTransports(EXIT_FLUSH_TIMEOUT_MS).catch(() => false)
-    ]).then(() => {
-      isFlushing = false;
-    });
-  });
-}
-
 // src/serialize.ts
 import superjson from "superjson";
 
@@ -222,7 +86,8 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--db-branch",
   "--no-db-branch",
-  "--no-code-change"
+  "--no-code-change",
+  "--dry-run"
 ]);
 var HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
 function usage(registry) {
@@ -239,12 +104,81 @@ Options:
   --grader-ids id1,id2
   --mock none|all|marked
   --db-branch, --no-db-branch
+  --dry-run (resolve inputs, run nothing)
   --params PATH
   --param name=value (repeatable)
   -h, --help`;
 }
 var ReplayCliHelp = class extends Error {
 };
+function parseSeedCases(raw, path) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    throw new BitfabError(`Seed file '${path}' is empty.`);
+  }
+  const values = trimmed.startsWith("[") ? JSON.parse(trimmed) : trimmed.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => JSON.parse(line));
+  return values.map((value, index) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new BitfabError(
+        `Seed case ${index} in '${path}' must be an object with an "input" array.`
+      );
+    }
+    const { input } = value;
+    if (!Array.isArray(input)) {
+      throw new BitfabError(
+        `Seed case ${index} in '${path}' is missing an "input" array. Wrap a single argument as [arg].`
+      );
+    }
+    return value;
+  });
+}
+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 import("./http-GJZJKNZZ.js");
+  await flushTraces2(3e4);
+  return { pipeline, traceFunctionKey, traceIds };
+}
+var SEED_USAGE = 'Usage: bitfab-replay --registry <path> <pipeline> --seed <cases.jsonl>\n\nEach case is a JSON object with an "input" array, plus optional "expected", "metadata", and "sessionId". A JSON array of those objects works too.';
+async function runSeedCli(registry, argv, io = {}) {
+  const stdout = io.stdout ?? console.log;
+  const stderr = io.stderr ?? console.error;
+  if (argv.some((value) => HELP_FLAGS.has(value))) {
+    throw new ReplayCliHelp(SEED_USAGE);
+  }
+  const pipeline = argv[0];
+  if (pipeline === void 0 || registry[pipeline] === void 0) {
+    throw new BitfabError(SEED_USAGE);
+  }
+  const seedIndex = argv.indexOf("--seed");
+  const casesPath = argv[seedIndex + 1];
+  if (casesPath === void 0 || casesPath.startsWith("--")) {
+    throw new BitfabError("--seed requires a path to a cases file.");
+  }
+  const readFile = io.readFile ?? defaultReadFile;
+  const cases = parseSeedCases(await readFile(casesPath), casesPath);
+  stderr(`[seed] Seeding ${cases.length} case(s) into "${pipeline}"...`);
+  const result = await seedFromRegistry(registry, pipeline, cases);
+  stderr(
+    `[seed] Wrote ${result.traceIds.length} trace(s) for "${result.traceFunctionKey}". Replay them with --trace-ids ${result.traceIds.slice(0, 3).join(",")}${result.traceIds.length > 3 ? ",..." : ""}`
+  );
+  stdout(JSON.stringify(result, null, 2));
+  return result;
+}
 function requirePositiveInteger(flag, raw) {
   const value = Number(raw);
   if (!Number.isInteger(value) || value < 1) {
@@ -293,6 +227,9 @@ function parseReplayCliArgs(registry, argv) {
         case "--no-code-change":
           parsed.noCodeChange = true;
           break;
+        case "--dry-run":
+          parsed.dryRun = true;
+          break;
       }
       continue;
     }
@@ -434,11 +371,22 @@ function valuesEqual(left, right) {
 function renderSummary(pipeline, result, stderr) {
   let same = 0;
   let changed = 0;
+  let matched = 0;
+  let missed = 0;
   let errors = 0;
   for (const item of result.items) {
     if (item.error !== null) {
       errors += 1;
-    } else if (valuesEqual(item.result, item.originalOutput)) {
+      continue;
+    }
+    const equal = valuesEqual(item.result, item.originalOutput);
+    if (item.ingestionType === "seeded") {
+      if (equal) {
+        matched += 1;
+      } else {
+        missed += 1;
+      }
+    } else if (equal) {
       same += 1;
     } else {
       changed += 1;
@@ -447,14 +395,39 @@ function renderSummary(pipeline, result, stderr) {
   stderr("\n\u2500\u2500\u2500 Summary \u2500\u2500\u2500");
   stderr(`  Pipeline: ${pipeline}`);
   stderr(`  Replayed: ${result.items.length}`);
-  stderr(`  Same:     ${same}`);
-  stderr(`  Changed:  ${changed}`);
+  if (same > 0 || changed > 0 || matched + missed === 0) {
+    stderr(`  Same:     ${same}`);
+    stderr(`  Changed:  ${changed}`);
+  }
+  if (matched > 0 || missed > 0) {
+    stderr(`  Matched expected: ${matched}`);
+    stderr(`  Missed expected:  ${missed}`);
+  }
   if (errors > 0) {
     stderr(`  Errors:   ${errors}`);
   }
   stderr(`
   ${result.testRunUrl}`);
 }
+function renderDryRun(pipeline, result, stderr) {
+  stderr("\n\u2500\u2500\u2500 Dry run \u2500\u2500\u2500");
+  stderr(`  Pipeline: ${pipeline}`);
+  stderr(`  Resolved: ${result.items.length} (nothing was executed)`);
+  for (const item of result.items) {
+    stderr(`
+  ${item.originalTraceId}`);
+    stderr(`    args: ${safeJson(item.input)}`);
+  }
+  stderr(`
+  ${result.testRunUrl}`);
+}
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
 function reportReplayError(error, stderr) {
   for (const item of error.items) {
     stderr(
@@ -493,6 +466,7 @@ async function runReplayCli(registry, argv = typeof process === "undefined" ? []
       dbBranch: args.dbBranch && registrationOptions.dbBranch !== void 0 && registrationOptions.dbBranch !== false ? registrationOptions.dbBranch : args.dbBranch
     },
     ...args.noCodeChange === true ? { codeChangeDescription: null, codeChangeFiles: null } : {},
+    ...args.dryRun === true ? { dryRun: true } : {},
     ...codeChange === void 0 ? {} : {
       codeChangeDescription: codeChange.description,
       codeChangeFiles: codeChange.files
@@ -517,7 +491,7 @@ async function runReplayCli(registry, argv = typeof process === "undefined" ? []
     options.limit = registrationOptions.limit ?? 10;
   }
   stderr(
-    `[replay] Replaying ${options.traceIds?.length ?? options.limit ?? "dataset"} traces from "${traceFunctionKey}"...`
+    `[replay] ${args.dryRun === true ? "Resolving inputs for" : "Replaying"} ${options.traceIds?.length ?? options.limit ?? "dataset"} traces from "${traceFunctionKey}"...`
   );
   try {
     const result = await registration.client.replay(
@@ -525,8 +499,17 @@ async function runReplayCli(registry, argv = typeof process === "undefined" ? []
       registration.fn,
       options
     );
-    renderSummary(args.pipeline, result, stderr);
+    if (args.dryRun === true) {
+      renderDryRun(args.pipeline, result, stderr);
+    } else {
+      renderSummary(args.pipeline, result, stderr);
+    }
     stdout(serializeReplayResult(result));
+    if (result.items.length === 0) {
+      throw new BitfabError(
+        `No traces matched "${traceFunctionKey}", so nothing was replayed. Seed cases with --seed, or capture a trace first.`
+      );
+    }
     return result;
   } catch (error) {
     if (error instanceof ReplayError) {
@@ -537,7 +520,7 @@ async function runReplayCli(registry, argv = typeof process === "undefined" ? []
 }
 
 // src/replayCli.ts
-var USAGE = "Usage: bitfab-replay --registry <path> <pipeline> [options]\nRun bitfab-replay --registry <path> --help to list replay options.";
+var USAGE = "Usage: bitfab-replay --registry <path> <pipeline> [options]\n       bitfab-replay --registry <path> <pipeline> --seed <cases.jsonl>\nRun bitfab-replay --registry <path> --help to list replay options.";
 async function parseCommandArgs(argv) {
   if (argv.some((value) => value === "--help" || value === "-h") && !argv.includes("--registry")) {
     throw new ReplayCliHelp(USAGE);
@@ -577,6 +560,9 @@ function resolveRegistry(moduleValue, path) {
 async function runReplayCommand(argv, io = {}, importer = importRegistry) {
   const { registryPath, replayArgs } = await parseCommandArgs(argv);
   const registry = resolveRegistry(await importer(registryPath), registryPath);
+  if (replayArgs.includes("--seed")) {
+    return runSeedCli(registry, replayArgs, io);
+  }
   return runReplayCli(registry, replayArgs, io);
 }
 async function runReplayMain(argv, io = {}) {