@bitfab/sdk 0.38.2 → 0.38.3

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, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, MockOverride, MockOverrideCtx, MockStrategy, MockValue, NodeMatcher, ProviderDefinition, ReplayBranch, ReplayError, ReplayItem, ReplayItemFinishProgress, ReplayItemStartProgress, ReplayOptions, ReplayProgress, ReplayProgressItem, ReplayResult, SUPPORTED_PROVIDERS, SpanLookup, SpanMethodDecorator, SpanMethodDecoratorContext, SpanNodeMeta, SpanOccurrence, SpanOptions, SpanType, TokenUsage, TraceResponse, TracingProcessor, VercelCallParams, VercelGenerateResult, VercelStreamResult, WrapBAMLOptions, WrappedBamlFn, __version__, 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, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, MockOverride, MockOverrideCtx, MockStrategy, MockValue, NodeMatcher, 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';

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, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, MockOverride, MockOverrideCtx, MockStrategy, MockValue, NodeMatcher, ProviderDefinition, ReplayBranch, ReplayError, ReplayItem, ReplayItemFinishProgress, ReplayItemStartProgress, ReplayOptions, ReplayProgress, ReplayProgressItem, ReplayResult, SUPPORTED_PROVIDERS, SpanLookup, SpanMethodDecorator, SpanMethodDecoratorContext, SpanNodeMeta, SpanOccurrence, SpanOptions, SpanType, TokenUsage, TraceResponse, TracingProcessor, VercelCallParams, VercelGenerateResult, VercelStreamResult, WrapBAMLOptions, WrappedBamlFn, __version__, 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, BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, CaptureWhen, CapturedSpan, CodeChangeFile, CurrentSpan, CurrentTrace, DEFAULT_SERVICE_URL, DbBranchOptions, DbBranchReplayError, DbBranchTimings, DbSnapshotConfig, DbSnapshotProvider, DbSnapshotRef, DetachedTrace, HttpClient, MockOverride, MockOverrideCtx, MockStrategy, MockValue, NodeMatcher, 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';

package/dist/node.js

@@ -7,11 +7,12 @@ import {
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   SUPPORTED_PROVIDERS,
+  defineReplayRegistry,
   finalizers,
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-CWXCVY75.js";
+} from "./chunk-RJPHMJWO.js";
 import "./chunk-GFBQ2AMO.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -24,7 +25,7 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-SU7EAKOV.js";
+} from "./chunk-WX6AEFCP.js";
 import {
   assertAsyncStorageRegistered,
   registerAsyncLocalStorageClass
@@ -55,6 +56,7 @@ export {
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
+  defineReplayRegistry,
   finalizers,
   flushTraces,
   getCurrentReplayBranch,

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-A5UVFNZ3.js → replay-FAO7D7CG.js}

@@ -7,7 +7,7 @@ import {
   serializeReplayResult,
   sleepForReplayPersistence,
   waitForReplayPersistence
-} from "./chunk-SU7EAKOV.js";
+} from "./chunk-WX6AEFCP.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
@@ -19,4 +19,4 @@ export {
   sleepForReplayPersistence,
   waitForReplayPersistence
 };
-//# sourceMappingURL=replay-A5UVFNZ3.js.map
+//# sourceMappingURL=replay-FAO7D7CG.js.map

package/dist/replayCli.js

@@ -0,0 +1,620 @@
+#!/usr/bin/env node
+
+// 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";
+
+// src/replay.ts
+var BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
+function reportReplayProgress(progress) {
+  const stderr = typeof process !== "undefined" ? process.stderr : void 0;
+  if (!stderr) {
+    return;
+  }
+  try {
+    stderr.write(
+      `${BITFAB_PROGRESS_PREFIX}${JSON.stringify(progress, replayJsonReplacer)}
+`
+    );
+  } catch {
+  }
+}
+var ReplayError = class extends BitfabError {
+  constructor(message, items, testRunId, testRunUrl, cause) {
+    super(message, testRunUrl);
+    this.items = items;
+    this.testRunId = testRunId;
+    this.testRunUrl = testRunUrl;
+    this.cause = cause;
+    this.name = "ReplayError";
+  }
+};
+var DbBranchReplayError = class extends BitfabError {
+  constructor(code, message, originalTraceId, cause) {
+    super(message);
+    this.code = code;
+    this.originalTraceId = originalTraceId;
+    this.cause = cause;
+    this.name = "DbBranchReplayError";
+  }
+};
+function replayJsonReplacer(_key, value) {
+  if (value instanceof Error) {
+    const serialized = {
+      name: value.name,
+      message: value.message,
+      stack: value.stack
+    };
+    if (value instanceof DbBranchReplayError) {
+      serialized.code = value.code;
+      serialized.originalTraceId = value.originalTraceId;
+      if (value.cause !== void 0) {
+        serialized.cause = value.cause;
+      }
+    }
+    return serialized;
+  }
+  return value;
+}
+function serializeReplayResult(result) {
+  return JSON.stringify(result, replayJsonReplacer, 2);
+}
+
+// src/replayRegistry.ts
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--limit",
+  "--trace-ids",
+  "--name",
+  "--concurrency",
+  "--max-concurrency",
+  "--code-change",
+  "--experiment-group-id",
+  "--dataset-id",
+  "--grader-ids",
+  "--mock",
+  "--param",
+  "--params"
+]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "--db-branch",
+  "--no-db-branch",
+  "--no-code-change"
+]);
+var HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+function usage(registry) {
+  return `Usage: bitfab-replay --registry <path> <${Object.keys(registry).join("|")}> [options]
+
+Options:
+  --limit N
+  --trace-ids id1,id2
+  --name NAME
+  --concurrency N, --max-concurrency N
+  --code-change PATH, --no-code-change
+  --experiment-group-id UUID
+  --dataset-id UUID
+  --grader-ids id1,id2
+  --mock none|all|marked
+  --db-branch, --no-db-branch
+  --params PATH
+  --param name=value (repeatable)
+  -h, --help`;
+}
+var ReplayCliHelp = class extends Error {
+};
+function requirePositiveInteger(flag, raw) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new BitfabError(
+      `${flag} must be a positive integer (received '${raw}').`
+    );
+  }
+  return value;
+}
+function commaSeparated(flag, raw) {
+  const values = raw.split(",").map((value) => value.trim()).filter((value) => value.length > 0);
+  if (values.length === 0) {
+    throw new BitfabError(`${flag} must contain at least one value.`);
+  }
+  return values;
+}
+function parseReplayCliArgs(registry, argv) {
+  if (argv.some((value) => HELP_FLAGS.has(value))) {
+    throw new ReplayCliHelp(usage(registry));
+  }
+  const pipeline = argv[0];
+  if (pipeline === void 0 || registry[pipeline] === void 0) {
+    throw new BitfabError(usage(registry));
+  }
+  const parsed = { pipeline, params: [] };
+  for (let index = 1; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (BOOLEAN_FLAGS.has(flag)) {
+      switch (flag) {
+        case "--db-branch":
+          if (parsed.dbBranch === false) {
+            throw new BitfabError(
+              "--db-branch and --no-db-branch cannot be used together."
+            );
+          }
+          parsed.dbBranch = true;
+          break;
+        case "--no-db-branch":
+          if (parsed.dbBranch === true) {
+            throw new BitfabError(
+              "--db-branch and --no-db-branch cannot be used together."
+            );
+          }
+          parsed.dbBranch = false;
+          break;
+        case "--no-code-change":
+          parsed.noCodeChange = true;
+          break;
+      }
+      continue;
+    }
+    if (!VALUE_FLAGS.has(flag)) {
+      throw new BitfabError(
+        `Unknown replay option '${flag}'.
+${usage(registry)}`
+      );
+    }
+    const raw = argv[index + 1];
+    if (raw === void 0 || raw.startsWith("--")) {
+      throw new BitfabError(`${flag} requires a value.`);
+    }
+    index += 1;
+    switch (flag) {
+      case "--limit":
+        parsed.limit = requirePositiveInteger(flag, raw);
+        break;
+      case "--trace-ids":
+        parsed.traceIds = commaSeparated(flag, raw);
+        break;
+      case "--name":
+        parsed.name = raw;
+        break;
+      case "--concurrency":
+      case "--max-concurrency":
+        parsed.maxConcurrency = requirePositiveInteger(flag, raw);
+        break;
+      case "--code-change":
+        parsed.codeChangePath = raw;
+        break;
+      case "--experiment-group-id":
+        parsed.experimentGroupId = raw;
+        break;
+      case "--dataset-id":
+        parsed.datasetId = raw;
+        break;
+      case "--grader-ids":
+        parsed.graderIds = commaSeparated(flag, raw);
+        break;
+      case "--mock":
+        if (raw !== "none" && raw !== "all" && raw !== "marked") {
+          throw new BitfabError(
+            `--mock must be one of: none, all, marked (received '${raw}').`
+          );
+        }
+        parsed.mock = raw;
+        break;
+      case "--params":
+        parsed.paramsPath = raw;
+        break;
+      case "--param":
+        parsed.params.push(raw);
+        break;
+    }
+  }
+  if (parsed.traceIds !== void 0 && parsed.datasetId !== void 0) {
+    throw new BitfabError(
+      "--trace-ids and --dataset-id select different replay sources and cannot be used together."
+    );
+  }
+  if (parsed.codeChangePath !== void 0 && parsed.noCodeChange === true) {
+    throw new BitfabError(
+      "--code-change and --no-code-change cannot be used together."
+    );
+  }
+  return parsed;
+}
+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;
+}
+async function defaultReadFile(path) {
+  const fs = await import("fs/promises").catch(() => null);
+  if (fs === null) {
+    throw new BitfabError(
+      "--code-change requires a runtime that can read local files."
+    );
+  }
+  return fs.readFile(path, "utf8");
+}
+async function loadCodeChange(path, readFile) {
+  if (path === void 0) {
+    return void 0;
+  }
+  const value = JSON.parse(await readFile(path));
+  if (typeof value.description !== "string" || !Array.isArray(value.files)) {
+    throw new BitfabError(
+      `Invalid --code-change file '${path}': expected { description, files }.`
+    );
+  }
+  return { description: value.description, files: value.files };
+}
+function parseParameter(raw) {
+  const separator = raw.indexOf("=");
+  const key = raw.slice(0, separator).trim();
+  if (separator < 1 || key.length === 0) {
+    throw new BitfabError(
+      `Invalid --param '${raw}': expected a non-empty name=value pair.`
+    );
+  }
+  const value = raw.slice(separator + 1);
+  try {
+    return [key, JSON.parse(value)];
+  } catch {
+    return [key, value];
+  }
+}
+async function loadParameters(path, rawParameters, readFile) {
+  let params = {};
+  if (path !== void 0) {
+    const value = JSON.parse(await readFile(path));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new BitfabError(
+        `Invalid --params file '${path}': expected a JSON object.`
+      );
+    }
+    params = { ...value };
+  }
+  for (const raw of rawParameters) {
+    const [key, value] = parseParameter(raw);
+    params[key] = value;
+  }
+  return params;
+}
+function valuesEqual(left, right) {
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return Object.is(left, right);
+  }
+}
+function renderSummary(pipeline, result, stderr) {
+  let same = 0;
+  let changed = 0;
+  let errors = 0;
+  for (const item of result.items) {
+    if (item.error !== null) {
+      errors += 1;
+    } else if (valuesEqual(item.result, item.originalOutput)) {
+      same += 1;
+    } else {
+      changed += 1;
+    }
+  }
+  stderr("\n\u2500\u2500\u2500 Summary \u2500\u2500\u2500");
+  stderr(`  Pipeline: ${pipeline}`);
+  stderr(`  Replayed: ${result.items.length}`);
+  stderr(`  Same:     ${same}`);
+  stderr(`  Changed:  ${changed}`);
+  if (errors > 0) {
+    stderr(`  Errors:   ${errors}`);
+  }
+  stderr(`
+  ${result.testRunUrl}`);
+}
+function reportReplayError(error, stderr) {
+  for (const item of error.items) {
+    stderr(
+      `${item.originalTraceId}: ${String(item.traceError ?? item.replayError ?? item.error)}`
+    );
+  }
+}
+async function runReplayCli(registry, argv = typeof process === "undefined" ? [] : process.argv.slice(2), io = {}) {
+  const stdout = io.stdout ?? console.log;
+  const stderr = io.stderr ?? console.error;
+  const args = parseReplayCliArgs(registry, argv);
+  const registration = registry[args.pipeline];
+  const traceFunctionKey = resolveTraceFunctionKey(registration);
+  const readFile = io.readFile ?? defaultReadFile;
+  const params = await loadParameters(args.paramsPath, args.params, readFile);
+  const dynamicOptions = await registration.optionsFactory?.({ params });
+  const registrationOptions = {
+    ...registration.options,
+    ...dynamicOptions
+  };
+  if (registrationOptions.traceIds !== void 0 && registrationOptions.datasetId !== void 0) {
+    throw new BitfabError(
+      "Replay registry options traceIds and datasetId select different sources and cannot be used together."
+    );
+  }
+  const codeChange = await loadCodeChange(args.codeChangePath, readFile);
+  const options = {
+    ...registrationOptions,
+    ...args.name === void 0 ? {} : { name: args.name },
+    ...args.maxConcurrency === void 0 ? {} : { maxConcurrency: args.maxConcurrency },
+    ...args.experimentGroupId === void 0 ? {} : { experimentGroupId: args.experimentGroupId },
+    ...args.datasetId === void 0 ? {} : { datasetId: args.datasetId },
+    ...args.graderIds === void 0 ? {} : { graderIds: args.graderIds },
+    ...args.mock === void 0 ? {} : { mock: args.mock },
+    ...args.dbBranch === void 0 ? {} : {
+      dbBranch: args.dbBranch && registrationOptions.dbBranch !== void 0 && registrationOptions.dbBranch !== false ? registrationOptions.dbBranch : args.dbBranch
+    },
+    ...args.noCodeChange === true ? { codeChangeDescription: null, codeChangeFiles: null } : {},
+    ...codeChange === void 0 ? {} : {
+      codeChangeDescription: codeChange.description,
+      codeChangeFiles: codeChange.files
+    },
+    onItemStart: reportReplayProgress,
+    onItemFinish: reportReplayProgress
+  };
+  if (args.traceIds !== void 0) {
+    options.traceIds = args.traceIds;
+    options.datasetId = void 0;
+    options.limit = void 0;
+  } else if (args.datasetId !== void 0) {
+    options.traceIds = void 0;
+    options.limit = void 0;
+  } else if (args.limit !== void 0) {
+    options.traceIds = void 0;
+    options.datasetId = void 0;
+    options.limit = args.limit;
+  } else if (registrationOptions.traceIds !== void 0 || registrationOptions.datasetId !== void 0) {
+    options.limit = void 0;
+  } else {
+    options.limit = registrationOptions.limit ?? 10;
+  }
+  stderr(
+    `[replay] Replaying ${options.traceIds?.length ?? options.limit ?? "dataset"} traces from "${traceFunctionKey}"...`
+  );
+  try {
+    const result = await registration.client.replay(
+      traceFunctionKey,
+      registration.fn,
+      options
+    );
+    renderSummary(args.pipeline, result, stderr);
+    stdout(serializeReplayResult(result));
+    return result;
+  } catch (error) {
+    if (error instanceof ReplayError) {
+      reportReplayError(error, stderr);
+    }
+    throw error;
+  }
+}
+
+// src/replayCli.ts
+var USAGE = "Usage: bitfab-replay --registry <path> <pipeline> [options]\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);
+  }
+  const registryFlagIndex = argv.indexOf("--registry");
+  const registryPath = argv[registryFlagIndex + 1];
+  if (registryFlagIndex === -1 || registryPath === void 0 || registryPath.startsWith("--")) {
+    throw new BitfabError(USAGE);
+  }
+  const replayArgs = argv.filter(
+    (_value, index) => index !== registryFlagIndex && index !== registryFlagIndex + 1
+  );
+  if (replayArgs.length === 0) {
+    throw new BitfabError(USAGE);
+  }
+  const { resolve } = await import("path");
+  return { registryPath: resolve(registryPath), replayArgs };
+}
+async function importRegistry(path) {
+  const { pathToFileURL } = await import("url");
+  return tsImport(pathToFileURL(path).href, import.meta.url);
+}
+function resolveRegistry(moduleValue, path) {
+  if (typeof moduleValue !== "object" || moduleValue === null) {
+    throw new BitfabError(
+      `Replay registry '${path}' must export a default registry.`
+    );
+  }
+  const registry = moduleValue.default;
+  if (typeof registry !== "object" || registry === null) {
+    throw new BitfabError(
+      `Replay registry '${path}' must export a default registry.`
+    );
+  }
+  return registry;
+}
+async function runReplayCommand(argv, io = {}, importer = importRegistry) {
+  const { registryPath, replayArgs } = await parseCommandArgs(argv);
+  const registry = resolveRegistry(await importer(registryPath), registryPath);
+  return runReplayCli(registry, replayArgs, io);
+}
+async function runReplayMain(argv, io = {}) {
+  const stdout = io.stdout ?? console.log;
+  const stderr = io.stderr ?? console.error;
+  try {
+    await runReplayCommand(argv, io);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof ReplayCliHelp) {
+      stdout(message);
+      return 0;
+    }
+    stderr(message);
+    return 1;
+  }
+}
+async function isEntrypoint() {
+  const executablePath = process.argv[1];
+  if (executablePath === void 0) {
+    return false;
+  }
+  const [{ realpath }, { fileURLToPath }] = await Promise.all([
+    import("fs/promises"),
+    import("url")
+  ]);
+  return await realpath(executablePath) === await realpath(fileURLToPath(import.meta.url));
+}
+void isEntrypoint().then((entrypoint) => {
+  if (entrypoint) {
+    void runReplayMain(process.argv.slice(2)).then((exitCode) => {
+      process.exitCode = exitCode;
+    });
+  }
+});
+export {
+  runReplayCommand,
+  runReplayMain
+};
+//# sourceMappingURL=replayCli.js.map