@bitfab/sdk 0.64.16 → 0.64.18

package/dist/chunk-NGKTKRCV.js

@@ -0,0 +1,1905 @@
+import {
+  BitfabError,
+  __version__,
+  flushTraces,
+  gitRunner,
+  readEnv,
+  replayContextReady,
+  runWithReplayContext,
+  unrefTimer,
+  warnOnce,
+  writeOnce
+} from "./chunk-7NPHFRQD.js";
+
+// src/codeChange.ts
+var MAX_FILES = 60;
+var MAX_FILE_BYTES = 5e5;
+var MAX_TOTAL_BYTES = 2e6;
+var NUL = String.fromCharCode(0);
+async function resolveAutoCodeChange(label) {
+  if (typeof process === "undefined") {
+    return null;
+  }
+  if (process.env?.BITFAB_DISABLE_CODE_CHANGE_CAPTURE) {
+    return null;
+  }
+  const fromEnv = await readCodeChangeFile();
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return captureCodeChangeFromGit(process.cwd?.() ?? ".", label);
+}
+async function readCodeChangeFile() {
+  const path = process.env?.BITFAB_CODE_CHANGE_PATH;
+  if (!path) {
+    return null;
+  }
+  try {
+    const { readFile } = await import("fs/promises");
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const files = Array.isArray(parsed?.files) && parsed.files.every(
+      (f) => typeof f === "object" && f !== null && !Array.isArray(f)
+    ) ? parsed.files : void 0;
+    const description = typeof parsed?.description === "string" ? parsed.description : void 0;
+    if (!files && description === void 0) {
+      return null;
+    }
+    return { description, files };
+  } catch {
+    return null;
+  }
+}
+async function captureCodeChangeFromGit(cwd, label) {
+  let readFile;
+  try {
+    ;
+    ({ readFile } = await import("fs/promises"));
+  } catch {
+    return null;
+  }
+  const git = await gitRunner({
+    timeoutMs: 3e4,
+    maxBuffer: 64 * 1024 * 1024,
+    keepProcessAlive: true
+  });
+  if (!git) {
+    return null;
+  }
+  try {
+    const root = (await git(cwd, ["rev-parse", "--show-toplevel"]))?.trim();
+    if (!root) {
+      return null;
+    }
+    const resolved = await resolveBase(git, root);
+    if (!resolved) {
+      return null;
+    }
+    const { base, against } = resolved;
+    const blobBytes = async (ref, path) => {
+      const out = await git(root, ["cat-file", "-s", `${ref}:${path}`]);
+      const n = out ? Number.parseInt(out.trim(), 10) : Number.NaN;
+      return Number.isFinite(n) ? n : 0;
+    };
+    const workingBytes = async (path) => {
+      try {
+        const { stat } = await import("fs/promises");
+        const { join } = await import("path");
+        return (await stat(join(root, path))).size;
+      } catch {
+        return 0;
+      }
+    };
+    const tracked = await git(root, [
+      "diff",
+      "--name-status",
+      "--find-renames",
+      "-z",
+      base,
+      "--",
+      ":!.bitfab"
+    ]);
+    const untracked = await git(root, [
+      "ls-files",
+      "--others",
+      "--exclude-standard",
+      "-z",
+      "--",
+      ":!.bitfab"
+    ]);
+    const entries = [
+      ...parseNameStatusZ(tracked ?? ""),
+      ...(untracked ?? "").split(NUL).filter((p) => p.length > 0).map((path) => ({ status: "A", beforePath: path, path }))
+    ];
+    if (entries.length === 0) {
+      return null;
+    }
+    const files = [];
+    let totalBytes = 0;
+    for (const { status, beforePath, path } of entries) {
+      if (files.length >= MAX_FILES) {
+        break;
+      }
+      const beforeBytes = status === "A" ? 0 : await blobBytes(base, beforePath);
+      const afterBytes = status === "D" ? 0 : await workingBytes(path);
+      if (beforeBytes > MAX_FILE_BYTES || afterBytes > MAX_FILE_BYTES) {
+        continue;
+      }
+      const before = (status === "A" ? "" : await git(root, ["show", `${base}:${beforePath}`]) ?? "").replace(/\r\n/g, "\n");
+      const after = (status === "D" ? "" : await readWorkingFile(readFile, root, path)).replace(/\r\n/g, "\n");
+      if (before === after) {
+        continue;
+      }
+      const size = Buffer.byteLength(before, "utf8") + Buffer.byteLength(after, "utf8");
+      if (totalBytes + size > MAX_TOTAL_BYTES || looksBinary(before) || looksBinary(after)) {
+        continue;
+      }
+      totalBytes += size;
+      files.push({ path, before, after });
+    }
+    if (files.length === 0) {
+      return null;
+    }
+    const subject = (await git(root, ["log", "-1", "--format=%s", "HEAD"]))?.trim();
+    const fileWord = files.length === 1 ? "file" : "files";
+    const head = label?.trim() || subject || "Working-tree change";
+    return {
+      description: `${head} (${files.length} ${fileWord} changed ${against})`,
+      files
+    };
+  } catch {
+    return null;
+  }
+}
+async function resolveBase(git, root) {
+  const forced = process.env?.BITFAB_CODE_CHANGE_BASE;
+  if (forced && await refExists(git, root, forced)) {
+    const base = (await git(root, ["merge-base", "HEAD", forced]))?.trim() || (await git(root, ["rev-parse", "--verify", forced]))?.trim() || null;
+    return base ? { base, against: `vs ${forced}` } : null;
+  }
+  return await refExists(git, root, "HEAD") ? { base: "HEAD", against: "uncommitted (vs HEAD)" } : null;
+}
+async function refExists(git, root, ref) {
+  return await git(root, ["rev-parse", "--verify", `${ref}^{object}`]) !== null;
+}
+async function readWorkingFile(readFile, root, path) {
+  try {
+    const { join } = await import("path");
+    return await readFile(join(root, path), "utf8");
+  } catch {
+    return "";
+  }
+}
+function parseNameStatusZ(raw) {
+  const parts = raw.split(NUL).filter((p) => p.length > 0);
+  const out = [];
+  let i = 0;
+  while (i + 1 < parts.length) {
+    const status = parts[i].charAt(0);
+    i += 1;
+    const beforePath = parts[i];
+    i += 1;
+    if ((status === "R" || status === "C") && i < parts.length) {
+      out.push({ status, beforePath, path: parts[i] });
+      i += 1;
+    } else {
+      out.push({ status, beforePath, path: beforePath });
+    }
+  }
+  return out;
+}
+function looksBinary(s) {
+  return s.slice(0, 8e3).includes(NUL);
+}
+
+// src/serialize.ts
+import superjson from "superjson";
+function deserializeValue(serialized) {
+  if (serialized.meta === void 0) {
+    return serialized.json;
+  }
+  return superjson.deserialize({
+    json: serialized.json,
+    meta: serialized.meta
+  });
+}
+
+// src/integrationFixture.ts
+var INTEGRATION_FIXTURE_CONTEXT_KEY = "__bitfabIntegrationFixture";
+var INTEGRATION_FIXTURE_VERSION = 1;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function extractIntegrationFixtures(spanData) {
+  const contexts = spanData.contexts;
+  if (!Array.isArray(contexts)) {
+    return void 0;
+  }
+  const fixtures = /* @__PURE__ */ new Map();
+  for (const context of contexts) {
+    if (!isRecord(context)) {
+      continue;
+    }
+    const fixture = context[INTEGRATION_FIXTURE_CONTEXT_KEY];
+    if (!isRecord(fixture) || fixture.version !== INTEGRATION_FIXTURE_VERSION || typeof fixture.name !== "string") {
+      continue;
+    }
+    fixtures.set(
+      fixture.name,
+      deserializeValue({
+        json: fixture.value,
+        ...fixture.valueMeta !== void 0 && { meta: fixture.valueMeta }
+      })
+    );
+  }
+  return fixtures.size > 0 ? fixtures : void 0;
+}
+
+// src/mockOverride.ts
+function normalizeMockOverrides(mockOverride) {
+  if (mockOverride === void 0) {
+    return [];
+  }
+  const overrides = Array.isArray(mockOverride) ? mockOverride : [mockOverride];
+  return overrides.map(
+    (override) => typeof override === "function" ? { match: () => true, value: override } : override
+  );
+}
+
+// src/randomUuid.ts
+function randomUuid() {
+  const globalCrypto = globalThis.crypto;
+  if (typeof globalCrypto?.randomUUID === "function") {
+    try {
+      return globalCrypto.randomUUID();
+    } catch {
+    }
+  }
+  warnOnce(
+    "crypto-unavailable",
+    "global crypto.randomUUID is unavailable; using a non-cryptographic fallback for trace/span ids. Tracing works normally (ids are correlation-only, not security-sensitive)."
+  );
+  return fallbackUuidV4();
+}
+function fallbackUuidV4() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const rand = Math.random() * 16 | 0;
+    const value = char === "x" ? rand : rand & 3 | 8;
+    return value.toString(16);
+  });
+}
+
+// src/replayHeartbeat.ts
+var REPLAY_HEARTBEAT_INTERVAL_MS = 6e4;
+function startReplayHeartbeat(send) {
+  let stopped = false;
+  let inFlight;
+  const timer = setInterval(() => {
+    if (stopped || inFlight !== void 0) {
+      return;
+    }
+    inFlight = send().catch(() => void 0).finally(() => {
+      inFlight = void 0;
+    });
+  }, REPLAY_HEARTBEAT_INTERVAL_MS);
+  unrefTimer(timer);
+  return {
+    stop: async () => {
+      stopped = true;
+      clearInterval(timer);
+      await inFlight;
+    }
+  };
+}
+
+// src/replayInterrupt.ts
+var REPLAY_INTERRUPT_SIGNALS = [
+  "SIGINT",
+  "SIGTERM"
+];
+var replayListeners = /* @__PURE__ */ new Set();
+function signalCapableProcess() {
+  if (typeof process === "undefined" || typeof process.on !== "function") {
+    return void 0;
+  }
+  return process;
+}
+function describeReplayInterrupt(experimentId, markedInterrupted) {
+  if (markedInterrupted) {
+    return `[replay] Experiment ${experimentId} interrupted.`;
+  }
+  return `[replay] Experiment ${experimentId} stopped, but Bitfab could not mark it interrupted. It will be marked interrupted within 15 minutes. A resume in the next two minutes may be refused as still running.`;
+}
+function reportInterrupted(experimentId, markedInterrupted) {
+  try {
+    console.error(describeReplayInterrupt(experimentId, markedInterrupted));
+  } catch {
+  }
+}
+function installReplayInterruptHandlers(target) {
+  const host = signalCapableProcess();
+  if (host === void 0) {
+    return { remove: () => {
+    }, interrupted: () => false };
+  }
+  const handlers = /* @__PURE__ */ new Map();
+  const removeHandlers = () => {
+    for (const [signal, handler] of handlers) {
+      host.removeListener(signal, handler);
+      replayListeners.delete(handler);
+    }
+    handlers.clear();
+  };
+  let interrupting = false;
+  const handleSignal = async (signal) => {
+    const hostHandlesSignal = host.listeners(signal).some((listener) => !replayListeners.has(listener));
+    const markedInterrupted = await target.interrupt();
+    removeHandlers();
+    if (target.onInterrupt !== void 0) {
+      try {
+        target.onInterrupt({
+          experimentId: target.experimentId,
+          experimentUrl: target.experimentUrl,
+          signal,
+          markedInterrupted
+        });
+      } catch {
+      }
+      return;
+    }
+    reportInterrupted(target.experimentId, markedInterrupted);
+    if (!hostHandlesSignal) {
+      host.kill(host.pid, signal);
+    }
+  };
+  for (const signal of REPLAY_INTERRUPT_SIGNALS) {
+    const handler = () => {
+      if (interrupting) {
+        return;
+      }
+      interrupting = true;
+      void handleSignal(signal);
+    };
+    handlers.set(signal, handler);
+    replayListeners.add(handler);
+    host.on(signal, handler);
+  }
+  return { remove: removeHandlers, interrupted: () => interrupting };
+}
+
+// src/replayInvocation.ts
+var REPLAY_EXECUTION_TARGET_ENV = "BITFAB_REPLAY_EXECUTION_TARGET";
+var HOSTED_EXECUTION_TARGET = "hosted";
+var CI_ENV = "CI";
+var CI_TRUE_VALUES = /* @__PURE__ */ new Set(["true", "1"]);
+var CI_PRESENCE_ENV_VARS = [
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "CIRCLECI",
+  "BUILDKITE",
+  "JENKINS_URL",
+  "TF_BUILD"
+];
+var MAX_FLAGS = 100;
+var MAX_FLAG_NAME_LENGTH = 100;
+var MAX_FLAG_STRING_LENGTH = 1e3;
+var MAX_FLAG_LIST_LENGTH = 100;
+var SECRET_FLAG_NAME = /key|token|secret|password/i;
+var CLI_FLAGS = /* @__PURE__ */ Symbol("bitfab.replayCliFlags");
+var METADATA_FLAG = "metadata";
+var CLI_FLAG_ALIASES = {
+  "max-concurrency": "concurrency",
+  "dataset-id": "dataset-ids"
+};
+var OPTION_FLAG_NAMES = {
+  maxConcurrency: "concurrency",
+  datasetId: "dataset-ids",
+  datasetIds: "dataset-ids"
+};
+function replayEnvironment() {
+  if (readEnv(REPLAY_EXECUTION_TARGET_ENV) === HOSTED_EXECUTION_TARGET) {
+    return "cloud_replay";
+  }
+  if (CI_TRUE_VALUES.has((readEnv(CI_ENV) ?? "").toLowerCase())) {
+    return "ci";
+  }
+  if (CI_PRESENCE_ENV_VARS.some((name) => (readEnv(name) ?? "") !== "")) {
+    return "ci";
+  }
+  return "local";
+}
+function flagScalar(value) {
+  if (typeof value === "string") {
+    return value.slice(0, MAX_FLAG_STRING_LENGTH);
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : void 0;
+  }
+  if (typeof value === "boolean" || value === null) {
+    return value;
+  }
+  return void 0;
+}
+function flagValue(value) {
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_FLAG_LIST_LENGTH).map(flagScalar);
+    return items.every((item) => item !== void 0) ? items : true;
+  }
+  const scalar = flagScalar(value);
+  return scalar === void 0 ? true : scalar;
+}
+function canonicalCliFlag(name) {
+  return CLI_FLAG_ALIASES[name] ?? name;
+}
+function optionFlagName(option) {
+  return OPTION_FLAG_NAMES[option] ?? option.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+function metadataKeys(value) {
+  const keys = Array.isArray(value) ? value.map((pair) => String(pair).split("=")[0]) : typeof value === "object" && value !== null ? Object.keys(value) : void 0;
+  return keys === void 0 ? true : [...new Set(keys)].sort();
+}
+function invocationFlags(entries) {
+  const flags = {};
+  const seen = /* @__PURE__ */ new Set();
+  for (const [name, value] of entries) {
+    if (seen.size >= MAX_FLAGS) {
+      break;
+    }
+    if (value === void 0 || seen.has(name) || name.length === 0 || name.length > MAX_FLAG_NAME_LENGTH || SECRET_FLAG_NAME.test(name)) {
+      continue;
+    }
+    flags[name] = flagValue(
+      name === METADATA_FLAG ? metadataKeys(value) : value
+    );
+    seen.add(name);
+  }
+  return flags;
+}
+function buildReplayInvocation(entries = []) {
+  return {
+    flags: invocationFlags(entries),
+    sdk: { language: "typescript", version: __version__ },
+    environment: replayEnvironment()
+  };
+}
+function safeReplayInvocation(build) {
+  try {
+    return build();
+  } catch {
+    return void 0;
+  }
+}
+function withCliFlags(options, flags) {
+  Object.defineProperty(options, CLI_FLAGS, {
+    value: flags,
+    enumerable: false
+  });
+  return options;
+}
+function cliFlags(options) {
+  return options?.[CLI_FLAGS];
+}
+
+// src/selectiveReplay.ts
+function replayNodeKey(node) {
+  return JSON.stringify([node.traceFunctionKey, node.spanName]);
+}
+function jsonFingerprint(value) {
+  const seen = /* @__PURE__ */ new Set();
+  function encode(input) {
+    if (input === null || typeof input === "boolean") {
+      return JSON.stringify(input);
+    }
+    if (typeof input === "string" && !input.startsWith("<unserializable")) {
+      return JSON.stringify(input);
+    }
+    if (typeof input === "number" && Number.isFinite(input) && !Object.is(input, -0)) {
+      return JSON.stringify(input);
+    }
+    if (typeof input !== "object" || input === null || seen.has(input)) {
+      throw new Error("Not a lossless JSON value");
+    }
+    seen.add(input);
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== (Array.isArray(input) ? Array.prototype : Object.prototype)) {
+      throw new Error("Not a plain JSON object");
+    }
+    if (Object.getOwnPropertySymbols(input).length > 0) {
+      throw new Error("Symbol properties are not recorded");
+    }
+    const keys = Object.keys(input);
+    if (Object.getOwnPropertyNames(input).length !== keys.length + (Array.isArray(input) ? 1 : 0)) {
+      throw new Error("Non-enumerable properties are not recorded");
+    }
+    if (Array.isArray(input) && (keys.length !== input.length || keys.some((key, index) => key !== String(index)))) {
+      throw new Error("Not a dense JSON array");
+    }
+    const properties = keys.map((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor || !("value" in descriptor)) {
+        throw new Error("Accessor properties are not replay inputs");
+      }
+      return `${Array.isArray(input) ? "" : `${JSON.stringify(key)}:`}${encode(descriptor.value)}`;
+    });
+    return Array.isArray(input) ? `[${properties.join(",")}]` : `{${properties.join(",")}}`;
+  }
+  try {
+    return encode(value);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/selectiveReplayRuntime.ts
+function validateSelectiveReplayOptions(options) {
+  const validNodes = (nodes) => Array.isArray(nodes) && nodes.length <= 100 && nodes.every(
+    (node) => typeof node?.traceFunctionKey === "string" && node.traceFunctionKey.length > 0 && node.traceFunctionKey.length <= 500 && typeof node.spanName === "string" && node.spanName.length > 0 && node.spanName.length <= 500
+  );
+  if (!options || !validNodes(options.mustRun) || options.mustRun.length === 0 || Object.keys(options).some((key) => key !== "mustRun")) {
+    throw new BitfabError(
+      "experimentalSelectiveReplay accepts only 1\u2013100 mustRun with traceFunctionKey and spanName. Declare replayReusable on eligible spans, not reusableNodes in the replay request."
+    );
+  }
+}
+function policyKey(options) {
+  return JSON.stringify(options.mustRun.map(replayNodeKey).sort());
+}
+var SelectiveReplayRuntime = class {
+  constructor(plan, options) {
+    this.plan = plan;
+    this.options = options;
+    this.nodes = /* @__PURE__ */ new Map();
+    this.children = /* @__PURE__ */ new Map();
+    this.runtimeParents = /* @__PURE__ */ new Map();
+    this.consumed = /* @__PURE__ */ new Map();
+    this.requiredScopes = /* @__PURE__ */ new Set();
+    this.recordings = /* @__PURE__ */ new Map();
+    this.reached = /* @__PURE__ */ new Set();
+    this.decisions = [];
+    this.assertionNames = /* @__PURE__ */ new Set();
+    this.assertionScopes = /* @__PURE__ */ new Set();
+    this.observedNames = /* @__PURE__ */ new Map();
+    this.unresolvedAssertions = [];
+    validateSelectiveReplayOptions(options);
+    if (plan?.version !== 4 || !Array.isArray(plan.nodes) || plan.nodes.length === 0 || plan.nodes.length > 500 || !Array.isArray(plan.unresolvedMustRun) || !Array.isArray(plan.assertions) || !plan.options) {
+      throw new BitfabError(
+        "Server did not return a compatible selective replay plan. Update the server or disable experimentalSelectiveReplay."
+      );
+    }
+    validateSelectiveReplayOptions(plan.options);
+    if (policyKey(plan.options) !== policyKey(options)) {
+      throw new BitfabError(
+        "Selective replay plan does not match the requested mustRun nodes."
+      );
+    }
+    this.required = new Set(options.mustRun.map(replayNodeKey));
+    for (const node of plan.nodes) {
+      if (typeof node.id !== "string" || this.nodes.has(node.id) || typeof node.traceFunctionKey !== "string" || typeof node.spanName !== "string" || typeof node.mustRun !== "boolean" || typeof node.reusable !== "boolean") {
+        throw new BitfabError("Invalid selective replay node.");
+      }
+      this.nodes.set(node.id, node);
+      if (node.recording !== void 0) {
+        this.recordings.set(node.id, {
+          input: node.recording.kwargs === void 0 ? jsonFingerprint(node.recording.input) : void 0,
+          output: jsonFingerprint(node.recording.output)
+        });
+      }
+      if (node.parentId !== null) {
+        const siblings = this.children.get(node.parentId) ?? [];
+        siblings.push(node);
+        this.children.set(node.parentId, siblings);
+      }
+    }
+    const root = this.nodes.get(plan.rootId);
+    if (!root || root.parentId !== null || !root.mustRun) {
+      throw new BitfabError("Selective replay requires a live recorded root.");
+    }
+    const assertionIds = /* @__PURE__ */ new Set();
+    let wholeTrace = false;
+    for (const assertion of plan.assertions) {
+      const target = assertion?.target;
+      if (typeof assertion?.id !== "string" || assertion.id.length === 0 || assertionIds.has(assertion.id) || target !== null && (typeof target !== "object" || target.kind !== "output" && target.kind !== "span")) {
+        throw new BitfabError(
+          "Invalid selective replay assertion requirements."
+        );
+      }
+      assertionIds.add(assertion.id);
+      if (target === null) {
+        wholeTrace = true;
+      } else if (target.kind === "span") {
+        if (typeof target.name !== "string" || target.name.length === 0 || target.occurrence !== void 0 && target.occurrence !== "first" && target.occurrence !== "last" && !(Number.isInteger(target.occurrence) && typeof target.occurrence === "number" && target.occurrence >= 0)) {
+          throw new BitfabError("Invalid selective replay assertion target.");
+        }
+        this.assertionNames.add(target.name);
+        const count = plan.nodes.filter(
+          (node) => node.spanName === target.name
+        ).length;
+        if (count <= (typeof target.occurrence === "number" ? target.occurrence : 0)) {
+          this.unresolvedAssertions.push(assertion.id);
+        }
+      }
+    }
+    this.fullTraceForAssertions = wholeTrace || this.unresolvedAssertions.length > 0;
+    const recordedKeys = new Set(plan.nodes.map(replayNodeKey));
+    const unresolved = options.mustRun.filter(
+      (node) => !recordedKeys.has(replayNodeKey(node))
+    );
+    if (JSON.stringify(unresolved.map(replayNodeKey).sort()) !== JSON.stringify(plan.unresolvedMustRun.map(replayNodeKey).sort())) {
+      throw new BitfabError(
+        "Selective replay plan has incomplete mustRun coverage."
+      );
+    }
+    for (const node of plan.nodes) {
+      const ancestors = /* @__PURE__ */ new Set([node.id]);
+      let requiredByManifest = this.required.has(replayNodeKey(node));
+      let requiredForAssertion = this.fullTraceForAssertions || this.assertionNames.has(node.spanName);
+      let parentId = node.parentId;
+      while (parentId !== null) {
+        const parent = this.nodes.get(parentId);
+        if (!parent || ancestors.has(parentId) || node.mustRun && !parent.mustRun) {
+          throw new BitfabError("Invalid selective replay ancestry.");
+        }
+        ancestors.add(parentId);
+        requiredByManifest ||= this.required.has(replayNodeKey(parent));
+        requiredForAssertion ||= this.assertionNames.has(parent.spanName);
+        parentId = parent.parentId;
+      }
+      if (!ancestors.has(plan.rootId) || (requiredByManifest || unresolved.length > 0) && !node.mustRun) {
+        throw new BitfabError("Selective replay plan could hide required code.");
+      }
+      if (requiredForAssertion && !node.mustRun) {
+        throw new BitfabError(
+          "Selective replay plan could hide assertion evidence."
+        );
+      }
+    }
+  }
+  enter(params) {
+    const identity = {
+      traceFunctionKey: params.traceFunctionKey,
+      spanName: params.spanName
+    };
+    const key = replayNodeKey(identity);
+    const fingerprint = jsonFingerprint(params.inputs);
+    let node;
+    let matchReason = "unmatched-call";
+    if (params.parentSpanId === null) {
+      node = this.nodes.get(this.plan.rootId);
+    } else {
+      const recordedParent = this.runtimeParents.get(params.parentSpanId);
+      const consumed = this.consumed.get(params.parentSpanId) ?? /* @__PURE__ */ new Set();
+      this.consumed.set(params.parentSpanId, consumed);
+      const candidates = recordedParent ? (this.children.get(recordedParent) ?? []).filter(
+        (candidate) => replayNodeKey(candidate) === key && !consumed.has(candidate.id)
+      ) : [];
+      const exact = fingerprint === void 0 ? [] : candidates.filter(
+        (candidate) => this.recordings.get(candidate.id)?.input === fingerprint
+      );
+      node = exact.length === 1 ? exact[0] : exact.length === 0 && candidates.length === 1 ? candidates[0] : void 0;
+      if (node) {
+        consumed.add(node.id);
+      } else if (candidates.length > 0) {
+        matchReason = "ambiguous-call";
+        for (const candidate of candidates) {
+          consumed.add(candidate.id);
+        }
+      }
+    }
+    this.runtimeParents.set(params.spanId, node?.id ?? null);
+    const requiredByManifest = this.required.has(key) || params.parentSpanId !== null && this.requiredScopes.has(params.parentSpanId);
+    if (requiredByManifest) {
+      this.requiredScopes.add(params.spanId);
+    }
+    const requiredForAssertion = this.fullTraceForAssertions || this.assertionNames.has(params.spanName) || params.parentSpanId !== null && this.assertionScopes.has(params.parentSpanId);
+    if (requiredForAssertion) {
+      this.assertionScopes.add(params.spanId);
+    }
+    const mustRun = params.parentSpanId === null || requiredByManifest || node?.mustRun === true || requiredForAssertion || this.plan.unresolvedMustRun.length > 0;
+    const recording = node === void 0 ? void 0 : this.recordings.get(node.id);
+    const equalInputs = fingerprint !== void 0 && recording?.input === fingerprint;
+    const reusable = recording?.output !== void 0 && equalInputs && params.canReuseOutput;
+    const reason = mustRun ? requiredByManifest ? "must-run" : requiredForAssertion ? "assertion" : node?.reason ?? "unresolved-must-run" : !node ? matchReason : !equalInputs ? "input-drift-or-missing-recording" : !params.canReuseOutput ? "unsupported-output-boundary" : !params.safetyMock && !params.reuseAllowed ? "reuse-not-declared" : node.reason;
+    const decision = (action, why) => {
+      this.decisions.push({
+        ...identity,
+        originalSpanId: node?.id ?? null,
+        action,
+        reason: why
+      });
+    };
+    if (params.safetyMock && (mustRun || !reusable)) {
+      decision("blocked", `safety-conflict:${reason}`);
+      this.failure = new BitfabError(
+        `Selective replay cannot execute or safely reuse safety-mocked node ${params.spanName} (${reason}).`
+      );
+      throw this.failure;
+    }
+    if (!mustRun && reusable && (params.safetyMock || node?.reusable === true && params.reuseAllowed)) {
+      decision("mock", params.safetyMock ? "safety-mock" : "unchanged-inputs");
+      return {
+        mock: true,
+        output: JSON.parse(recording.output)
+      };
+    }
+    decision("run", reason);
+    this.observedNames.set(
+      params.spanName,
+      (this.observedNames.get(params.spanName) ?? 0) + 1
+    );
+    if (this.required.has(key)) {
+      this.reached.add(key);
+    }
+    return { mock: false };
+  }
+  assertNoSafetyConflict() {
+    if (this.failure) {
+      throw this.failure;
+    }
+  }
+  report() {
+    return {
+      decisions: this.decisions,
+      mustRunNotReached: this.options.mustRun.filter(
+        (node) => !this.reached.has(replayNodeKey(node))
+      ),
+      unresolvedMustRun: this.plan.unresolvedMustRun,
+      assertionIds: this.plan.assertions.map((assertion) => assertion.id),
+      unresolvedAssertions: this.unresolvedAssertions,
+      assertionTargetsNotReached: this.plan.assertions.flatMap(
+        ({ id, target }) => target?.kind === "span" && (this.observedNames.get(target.name) ?? 0) <= (typeof target.occurrence === "number" ? target.occurrence : 0) ? [id] : []
+      )
+    };
+  }
+};
+
+// src/replay.ts
+var REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
+var MAX_REPLAY_ATTEMPTS = 100;
+function expandReplayWork(serverItems, attempts) {
+  return Array.from(
+    { length: attempts },
+    (_, attempt) => serverItems.map((serverItem) => ({ serverItem, attempt }))
+  ).flat();
+}
+var RESUME_CONFLICTING_OPTIONS = [
+  "traceIds",
+  "limit",
+  "datasetId",
+  "datasetIds",
+  "attempts",
+  "graderIds",
+  "onlyWithAssertions",
+  "dryRun",
+  "experimentalSelectiveReplay"
+];
+var CARRIED_OVER_ERROR = "This item errored in an earlier run of this experiment, before it was resumed.";
+function validateResume(resume, options) {
+  if (resume.trim().length === 0) {
+    throw new BitfabError("resume must be the ID of the experiment to resume.");
+  }
+  const conflicting = RESUME_CONFLICTING_OPTIONS.filter(
+    (name) => options[name] !== void 0 && options[name] !== false
+  );
+  if (conflicting.length > 0) {
+    throw new BitfabError(
+      `resume continues experiment ${resume} with the traces, attempts, and graders it started with, so it cannot be combined with ${conflicting.join(", ")}. Drop those options, or start a new replay without resume.`
+    );
+  }
+}
+async function resumeReplaySession(httpClient, experimentId, traceFunctionKey, codeChangeFiles, force, requestedDbBranch) {
+  const response = await httpClient.resumeReplay(
+    experimentId,
+    traceFunctionKey,
+    codeChangeFiles,
+    force
+  );
+  const work = response.work.map(({ itemIndex, attempt }) => {
+    const serverItem = response.items[itemIndex];
+    if (serverItem === void 0) {
+      throw new BitfabError(
+        `Replay resume for experiment ${response.experimentId} named item ${itemIndex}, but the server returned only ${response.items.length} item(s).`
+      );
+    }
+    return { serverItem, attempt };
+  });
+  if (response.skippedOriginalTraceIds.length > 0) {
+    try {
+      console.warn(
+        `Bitfab: ${response.skippedOriginalTraceIds.length} trace(s) selected when experiment ${response.experimentId} started no longer exist, so resume skips them: ${response.skippedOriginalTraceIds.join(", ")}`
+      );
+    } catch {
+    }
+  }
+  if (requestedDbBranch !== void 0 && dbBranchEnabled(requestedDbBranch) !== response.includeDbBranchLease) {
+    try {
+      console.warn(
+        `Bitfab: experiment ${response.experimentId} started with database branching ${response.includeDbBranchLease ? "on" : "off"}, so resume keeps it ${response.includeDbBranchLease ? "on" : "off"} and ignores the dbBranch option passed here.`
+      );
+    } catch {
+    }
+  }
+  return {
+    experimentId: response.experimentId,
+    experimentUrl: response.experimentUrl,
+    attempts: response.attempts,
+    work,
+    finished: response.finished,
+    includeDbBranchLease: response.includeDbBranchLease,
+    dbBranchSettings: response.dbBranchSettings ?? void 0
+  };
+}
+function carriedOverReplayItem(finished) {
+  return {
+    traceId: finished.traceId,
+    originalTraceId: finished.originalTraceId,
+    originalSpanId: "",
+    sourceTraceId: finished.originalTraceId,
+    sourceSpanId: "",
+    attempt: finished.attempt,
+    input: [],
+    result: void 0,
+    originalOutput: void 0,
+    error: finished.hasError ? CARRIED_OVER_ERROR : null,
+    traceError: null,
+    replayError: null,
+    durationMs: null,
+    originalDurationMs: null,
+    originalTokens: null,
+    originalModel: null,
+    tokens: null,
+    model: null,
+    dbSnapshotRef: null,
+    dbBranchTimings: null,
+    carriedOver: true
+  };
+}
+function resolveAttempts(attempts) {
+  if (attempts === void 0) {
+    return 1;
+  }
+  if (!Number.isInteger(attempts) || attempts < 1 || attempts > MAX_REPLAY_ATTEMPTS) {
+    throw new BitfabError(
+      `attempts must be an integer from 1 to ${MAX_REPLAY_ATTEMPTS} (got ${attempts}).`
+    );
+  }
+  return attempts;
+}
+function resolveDatasetIds(options) {
+  if (options?.datasetId !== void 0 && options?.datasetIds !== void 0) {
+    throw new BitfabError(
+      "datasetId and datasetIds are the same selector: pass one dataset through datasetId, or several through datasetIds."
+    );
+  }
+  if (options?.datasetId !== void 0) {
+    return [options.datasetId];
+  }
+  if (options?.datasetIds === void 0) {
+    return void 0;
+  }
+  if (options.datasetIds.length === 0) {
+    throw new BitfabError("datasetIds must contain at least one dataset ID.");
+  }
+  return [...new Set(options.datasetIds)];
+}
+function dbBranchEnabled(dbBranch) {
+  return dbBranch !== void 0 && dbBranch !== false;
+}
+function resolveDbBranchSettings(dbBranch) {
+  if (!dbBranch || dbBranch === true) {
+    return void 0;
+  }
+  const { minCu, maxCu, warmupSql } = dbBranch;
+  const settings = {
+    ...minCu === void 0 ? {} : { minCu },
+    ...maxCu === void 0 ? {} : { maxCu },
+    ...warmupSql === void 0 ? {} : { warmupSql }
+  };
+  return Object.keys(settings).length === 0 ? void 0 : settings;
+}
+var REPLAY_OPTION_NAMES = [
+  "experimentalSelectiveReplay",
+  "limit",
+  "attempts",
+  "traceIds",
+  "name",
+  "notes",
+  "metadata",
+  "maxConcurrency",
+  "codeChangeDescription",
+  "codeChangeFiles",
+  "mock",
+  "mockOverride",
+  "dbBranch",
+  "experimentGroupId",
+  "datasetId",
+  "datasetIds",
+  "graderIds",
+  "onlyWithAssertions",
+  "skipAssertionJudging",
+  "judgeAssertions",
+  "adaptInputs",
+  "dryRun",
+  "onItemFinish",
+  "onProgress",
+  "onItemStart",
+  "onExperimentStart",
+  "onInterrupt",
+  "resume",
+  "force"
+];
+function explicitReplayOptions(options) {
+  const explicit = {};
+  for (const name of REPLAY_OPTION_NAMES) {
+    if (options?.[name] !== void 0) {
+      explicit[optionFlagName(name)] ??= options[name];
+    }
+  }
+  return explicit;
+}
+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, experimentId, experimentUrl, cause) {
+    super(message, experimentUrl);
+    this.items = items;
+    this.experimentId = experimentId;
+    this.experimentUrl = experimentUrl;
+    this.cause = cause;
+    this.name = "ReplayError";
+    this.testRunId = experimentId;
+    this.testRunUrl = experimentUrl;
+  }
+};
+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 isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function replayItemErrorMessage(error) {
+  if (error instanceof DbBranchReplayError) {
+    return `Replay requested a database branch for trace ${error.originalTraceId} but it could not be resolved (${error.code}): ${error.message}. The function was not run, because replaying it against the live database would produce a result that looks valid but did not use the historical data you asked for.`;
+  }
+  return errorMessage(error);
+}
+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);
+}
+async function preserveReplayFailure(operation, items, experimentId, experimentUrl) {
+  try {
+    return await operation();
+  } catch (cause) {
+    if (cause instanceof ReplayError) {
+      throw cause;
+    }
+    throw new ReplayError(
+      errorMessage(cause),
+      items,
+      experimentId,
+      experimentUrl,
+      cause
+    );
+  }
+}
+function deserializeInputs(spanData) {
+  const inputMeta = spanData.input_meta;
+  const rawInput = spanData.input;
+  if (inputMeta !== void 0 && inputMeta !== null) {
+    const deserialized = deserializeValue({ json: rawInput, meta: inputMeta });
+    if (Array.isArray(deserialized)) {
+      return deserialized;
+    }
+    return deserialized !== void 0 && deserialized !== null ? [deserialized] : [];
+  }
+  if (Array.isArray(rawInput)) {
+    return rawInput;
+  }
+  return rawInput !== void 0 && rawInput !== null ? [rawInput] : [];
+}
+function deserializeOutput(spanData) {
+  const outputMeta = spanData.output_meta;
+  const rawOutput = spanData.output;
+  if (outputMeta !== void 0 && outputMeta !== null) {
+    return deserializeValue({ json: rawOutput, meta: outputMeta });
+  }
+  return rawOutput;
+}
+function buildMockTree(rootNode) {
+  const spans = /* @__PURE__ */ new Map();
+  const counters = /* @__PURE__ */ new Map();
+  function walk(node) {
+    const key = node.traceFunctionKey;
+    if (key) {
+      const name = node.spanName || key;
+      const counterKey = `${key}:${name}`;
+      const index = counters.get(counterKey) ?? 0;
+      counters.set(counterKey, index + 1);
+      spans.set(`${counterKey}:${index}`, {
+        sourceSpanId: node.sourceSpanId,
+        externalSpanId: node.externalSpanId,
+        output: node.output,
+        outputMeta: node.outputMeta
+      });
+    }
+    for (const child of node.children) {
+      walk(child);
+    }
+  }
+  for (const child of rootNode.children) {
+    walk(child);
+  }
+  return { spans };
+}
+async function processItem(httpClient, serverItem, fn, experimentId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun, selectiveOptions) {
+  let lease = includeDbBranchLease ? serverItem.dbBranchLease : void 0;
+  let leaseError = includeDbBranchLease ? serverItem.dbBranchLeaseError : void 0;
+  let dbSnapshotRef = serverItem.dbSnapshotRef;
+  let dbBranchTimings = includeDbBranchLease ? serverItem.dbBranchTimings : void 0;
+  let inputs = [];
+  let originalOutput;
+  let result;
+  let error = null;
+  let traceError = null;
+  let replayError = null;
+  let replayDurationMs = null;
+  let replayStarted = null;
+  let selectiveReplay;
+  const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
+  const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
+  try {
+    if (includeDbBranchLease && experimentId !== null && !lease && !leaseError) {
+      let resolved;
+      try {
+        resolved = await httpClient.resolveDbBranchLease(
+          experimentId,
+          originalTraceId,
+          dbBranchSettings,
+          attempt
+        );
+      } catch (cause) {
+        throw new DbBranchReplayError(
+          "lease_request_failed",
+          `Bitfab could not request the database branch: ${errorMessage(cause)}`,
+          originalTraceId,
+          cause
+        );
+      }
+      lease = resolved.lease ?? void 0;
+      leaseError = resolved.leaseError ?? void 0;
+      dbSnapshotRef = resolved.dbSnapshotRef ?? dbSnapshotRef;
+      dbBranchTimings = resolved.timings ?? dbBranchTimings;
+    }
+    if (leaseError) {
+      throw new DbBranchReplayError(
+        leaseError.code,
+        leaseError.message,
+        originalTraceId
+      );
+    }
+    if (selectiveOptions !== void 0) {
+      if (serverItem.selectiveReplayPlan === void 0) {
+        throw new BitfabError(
+          "Server did not return a selective replay plan. Update the server or disable experimentalSelectiveReplay."
+        );
+      }
+      selectiveReplay = new SelectiveReplayRuntime(
+        serverItem.selectiveReplayPlan,
+        selectiveOptions
+      );
+    }
+    const span = await httpClient.getExternalSpan(originalSpanId, {
+      view: "replay"
+    });
+    const spanData = span.rawData?.span_data ?? {};
+    inputs = deserializeInputs(spanData);
+    originalOutput = deserializeOutput(spanData);
+    const integrationFixtures = extractIntegrationFixtures(spanData);
+    if (adaptInputs) {
+      const originalMetadata = serverItem.originalMetadata;
+      inputs = adaptInputs(inputs, {
+        originalTraceId,
+        originalSpanId,
+        // Deprecated aliases for originalTraceId/originalSpanId.
+        sourceTraceId: originalTraceId,
+        sourceSpanId: originalSpanId,
+        metadata: isPlainRecord(originalMetadata) ? { ...originalMetadata } : {}
+      });
+    }
+    const hasOverrides = resolvedOverrides.length > 0;
+    const needTree = selectiveReplay === void 0 && (mockStrategy === "all" || mockStrategy === "marked" || hasOverrides);
+    const includeOutputs = mockStrategy === "all";
+    let mockTree;
+    if (needTree) {
+      try {
+        const treeResponse = await httpClient.getSpanTree(originalSpanId, {
+          includeOutputs,
+          includeRootOutput: false
+        });
+        if (!treeResponse.root) {
+          throw new BitfabError(
+            `Replay mock strategy "${mockStrategy}"${hasOverrides ? " with overrides" : ""} requires a span tree root for original span ${originalSpanId}.`
+          );
+        }
+        mockTree = buildMockTree(treeResponse.root);
+      } catch (error2) {
+        if (mockStrategy !== "marked" || hasOverrides) {
+          throw error2;
+        }
+        mockTree = { spans: /* @__PURE__ */ new Map() };
+      }
+    }
+    const outputCache = /* @__PURE__ */ new Map();
+    const fetchSpanOutput = mockTree && !includeOutputs ? (externalSpanId) => {
+      let pending = outputCache.get(externalSpanId);
+      if (!pending) {
+        pending = httpClient.getExternalSpan(externalSpanId, { view: "replay" }).then(
+          (s) => deserializeOutput(
+            s.rawData?.span_data ?? {}
+          )
+        );
+        outputCache.set(externalSpanId, pending);
+      }
+      return pending;
+    } : void 0;
+    if (dryRun || experimentId === null) {
+      return {
+        traceId: null,
+        originalTraceId,
+        originalSpanId,
+        sourceTraceId: originalTraceId,
+        sourceSpanId: originalSpanId,
+        attempt,
+        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(
+        {
+          experimentId,
+          traceId: replayedTraceId,
+          inputSourceSpanId: span.id,
+          inputSourceTraceId: span.externalTraceId,
+          sourceBitfabTraceId: originalTraceId,
+          replayAttempt: attempt,
+          mockTree,
+          selectiveReplay,
+          callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
+          mockStrategy,
+          mockOverrides: hasOverrides ? resolvedOverrides : void 0,
+          fetchSpanOutput,
+          integrationFixtures,
+          dbBranchLease: lease,
+          dbBranchTimings
+        },
+        () => fn(...inputs)
+      );
+      result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
+      selectiveReplay?.assertNoSafetyConflict();
+      replayDurationMs = Math.round(performance.now() - replayStarted);
+    } catch (e) {
+      if (replayStarted !== null) {
+        replayDurationMs = Math.round(performance.now() - replayStarted);
+      }
+      traceError = e;
+      error = errorMessage(e);
+    }
+  } catch (e) {
+    if (replayStarted !== null) {
+      replayDurationMs = Math.round(performance.now() - replayStarted);
+    }
+    replayError = e;
+    error = replayItemErrorMessage(e);
+  } finally {
+    if (lease) {
+      try {
+        await httpClient.releaseDbBranchLease(lease.neonBranchId);
+      } catch (e) {
+        try {
+          console.warn(
+            `Bitfab: failed to release DB branch ${lease.neonBranchId} (TTL janitor will catch it): ${e instanceof Error ? e.message : String(e)}`
+          );
+        } catch {
+        }
+      }
+    }
+  }
+  const originalDurationMs = serverItem.originalDurationMs ?? serverItem.durationMs ?? null;
+  const originalModel = serverItem.originalModel ?? serverItem.model ?? null;
+  return {
+    // Written in by replay() from the complete-replay response once the server
+    // has minted this replay trace's row. Null until then: the client-side
+    // correlation id (replayedTraceId) is never surfaced as the item's traceId.
+    traceId: null,
+    originalTraceId,
+    originalSpanId,
+    // Deprecated aliases for originalTraceId/originalSpanId.
+    sourceTraceId: originalTraceId,
+    sourceSpanId: originalSpanId,
+    attempt,
+    input: inputs,
+    result,
+    originalOutput,
+    ...serverItem.ingestionType && {
+      ingestionType: serverItem.ingestionType
+    },
+    error,
+    traceError,
+    replayError,
+    durationMs: replayDurationMs,
+    ...selectiveReplay === void 0 ? {} : { selectiveReplay: selectiveReplay.report() },
+    originalDurationMs,
+    originalTokens: serverItem.originalTokens ?? serverItem.tokens ?? null,
+    originalModel,
+    // Filled in by replay() from the complete-replay response once the
+    // replay traces are persisted and their spans aggregated server-side.
+    // Null here (and on older servers) means "replay tokens not known".
+    tokens: null,
+    model: originalModel,
+    dbSnapshotRef: dbSnapshotRef ?? null,
+    dbBranchTimings: dbBranchTimings ?? null
+  };
+}
+async function waitForReplayPersistence(httpClient, experimentId, replayedTraceIds, replayLabels = {}, warn = console.warn) {
+  const deferredSettled = await httpClient.settleDeferredWork(
+    REPLAY_PERSISTENCE_TIMEOUT_MS
+  );
+  if (!deferredSettled) {
+    httpClient.takeTraceDeliveries(replayedTraceIds);
+    throw new BitfabError(
+      `Replay could not settle deferred span work before the deadline, so the expected span counts are incomplete (experiment ${experimentId}).`
+    );
+  }
+  if (!httpClient.hasClosedDeliveries(replayedTraceIds)) {
+    httpClient.takeTraceDeliveries(replayedTraceIds);
+    return {};
+  }
+  const flushed = await flushTraces(REPLAY_PERSISTENCE_TIMEOUT_MS);
+  const deliveries = httpClient.takeTraceDeliveries(replayedTraceIds);
+  const expectedSpanCounts = {};
+  const readBackTraceIds = {};
+  let allDelivered = true;
+  for (const [traceId, delivery] of Object.entries(deliveries)) {
+    if (delivery.serverTraceId !== void 0) {
+      readBackTraceIds[traceId] = delivery.serverTraceId;
+    }
+    if (!delivery.closed) {
+      continue;
+    }
+    expectedSpanCounts[traceId] = delivery.spanCount;
+    allDelivered = allDelivered && delivery.delivered;
+  }
+  if (allDelivered) {
+    return readBackTraceIds;
+  }
+  const deadline = Date.now() + REPLAY_PERSISTENCE_TIMEOUT_MS;
+  let missing = Object.keys(expectedSpanCounts);
+  while (true) {
+    const status = await httpClient.getReplayStatus(
+      experimentId,
+      expectedSpanCounts
+    );
+    const ready = status.traceIds ?? {};
+    Object.assign(readBackTraceIds, ready);
+    missing = Object.keys(expectedSpanCounts).filter(
+      (traceId) => ready[traceId] === void 0
+    );
+    if (missing.length === 0) {
+      return readBackTraceIds;
+    }
+    if (Date.now() >= deadline) {
+      break;
+    }
+    await sleepForReplayPersistence(
+      Math.min(100, Math.max(0, deadline - Date.now()))
+    );
+  }
+  for (const traceId of missing) {
+    warn(
+      unconfirmedReplayWarning(
+        replayLabels[traceId] ?? traceId,
+        REPLAY_PERSISTENCE_TIMEOUT_MS / 1e3,
+        flushed
+      )
+    );
+  }
+  return readBackTraceIds;
+}
+function unconfirmedReplayWarning(label, seconds, flushed) {
+  return `[bitfab] replay ${label} could not confirm all spans reached Bitfab within ${seconds}s. The run continues; Bitfab will show this replay as capture incomplete.${flushed ? "" : " Some spans likely never left this process."}`;
+}
+function sleepForReplayPersistence(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function mapWithConcurrency(tasks, maxConcurrency, onSettled, onStarted, shouldStop) {
+  const results = new Array(tasks.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < tasks.length && shouldStop?.() !== true) {
+      const index = nextIndex++;
+      onStarted?.(index);
+      const result = await tasks[index]();
+      results[index] = result;
+      await onSettled?.(result, index);
+    }
+  }
+  const workers = Array.from(
+    { length: Math.min(maxConcurrency, tasks.length) },
+    () => worker()
+  );
+  await Promise.all(workers);
+  return results.slice(0, nextIndex);
+}
+var JUDGE_ASSERTIONS_DEPRECATION_WARNING = "Bitfab: judgeAssertions is deprecated. Assertion judging is on by default; pass skipAssertionJudging: true (--skip-assertion-judging) to turn it off.";
+function warnJudgeAssertionsDeprecated(write = console.warn) {
+  writeOnce(
+    "judgeAssertions-deprecated",
+    JUDGE_ASSERTIONS_DEPRECATION_WARNING,
+    write
+  );
+}
+async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, registeredOverrides = []) {
+  if (options?.judgeAssertions !== void 0) {
+    warnJudgeAssertionsDeprecated();
+  }
+  if (options?.resume !== void 0) {
+    validateResume(options.resume, options);
+  } else if (options?.force === true) {
+    throw new BitfabError(
+      "force only applies when resuming an experiment. Pass it together with resume."
+    );
+  }
+  if (options?.experimentalSelectiveReplay !== void 0) {
+    validateSelectiveReplayOptions(options.experimentalSelectiveReplay);
+    if ((options.mock ?? "marked") !== "marked" || normalizeMockOverrides(options.mockOverride).length > 0 || registeredOverrides.length > 0) {
+      throw new BitfabError(
+        "experimentalSelectiveReplay requires mock: 'marked' and cannot be combined with mock overrides."
+      );
+    }
+  }
+  if (options?.traceIds !== void 0) {
+    if (options.traceIds.length === 0) {
+      throw new BitfabError("traceIds must contain at least one trace ID.");
+    }
+    if (options.traceIds.length > 100) {
+      throw new BitfabError(
+        `traceIds supports at most 100 trace IDs per replay (got ${options.traceIds.length}).`
+      );
+    }
+  }
+  const datasetIds = resolveDatasetIds(options);
+  if (options?.limit !== void 0 && options?.traceIds !== void 0) {
+    try {
+      console.warn(
+        "Bitfab: limit is ignored when traceIds is passed: the explicit trace ID list already determines how many traces replay."
+      );
+    } catch {
+    }
+  }
+  const requestedAttempts = resolveAttempts(options?.attempts);
+  const maxConcurrency = options?.maxConcurrency ?? 10;
+  if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
+    throw new BitfabError(
+      `maxConcurrency must be a positive integer (got ${maxConcurrency}).`
+    );
+  }
+  await replayContextReady;
+  let codeChangeDescription = options?.codeChangeDescription;
+  let codeChangeFiles = options?.codeChangeFiles;
+  if (codeChangeFiles === void 0) {
+    const captured = await resolveAutoCodeChange(options?.name);
+    if (captured) {
+      codeChangeFiles = captured.files;
+      if (codeChangeDescription === void 0) {
+        codeChangeDescription = captured.description;
+      }
+    }
+  }
+  const includeDbBranchLease = dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true;
+  let session;
+  if (options?.resume === void 0) {
+    const started = await httpClient.startReplay(
+      traceFunctionKey,
+      // limit is meaningless with explicit traceIds (the ID list determines
+      // the count), so it's omitted from the request entirely.
+      options?.traceIds ? void 0 : options?.limit ?? 5,
+      options?.traceIds,
+      options?.name,
+      codeChangeDescription,
+      codeChangeFiles,
+      // 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.
+      includeDbBranchLease,
+      options?.experimentGroupId,
+      datasetIds,
+      options?.graderIds,
+      resolveDbBranchSettings(options?.dbBranch),
+      requestedAttempts,
+      options?.adaptInputs !== void 0,
+      options?.onlyWithAssertions,
+      options?.skipAssertionJudging === true || options?.judgeAssertions === false,
+      options?.experimentalSelectiveReplay,
+      options?.notes,
+      options?.metadata,
+      options?.dryRun === true,
+      safeReplayInvocation(
+        () => buildReplayInvocation(
+          Object.entries(cliFlags(options) ?? explicitReplayOptions(options))
+        )
+      )
+    );
+    if (started.items.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 {
+      }
+    }
+    session = {
+      experimentId: started.experimentId,
+      experimentUrl: started.experimentUrl,
+      attempts: requestedAttempts,
+      work: expandReplayWork(started.items, requestedAttempts),
+      finished: [],
+      includeDbBranchLease,
+      dbBranchSettings: resolveDbBranchSettings(options?.dbBranch)
+    };
+  } else {
+    session = await resumeReplaySession(
+      httpClient,
+      options.resume,
+      traceFunctionKey,
+      codeChangeFiles,
+      options.force,
+      options.dbBranch
+    );
+  }
+  const { experimentId } = session;
+  if (experimentId === null || session.experimentUrl === null) {
+    return runReplaySession(
+      httpClient,
+      fn,
+      session,
+      null,
+      maxConcurrency,
+      () => {
+      },
+      () => {
+      },
+      () => false,
+      options,
+      registeredOverrides
+    );
+  }
+  const fullExperimentUrl = `${serviceUrl}${session.experimentUrl}`;
+  const heartbeat = startReplayHeartbeat(
+    () => httpClient.heartbeatReplay(experimentId)
+  );
+  const interruptReplay = async () => {
+    await heartbeat.stop();
+    return httpClient.interruptReplay(experimentId);
+  };
+  const interruptHandlers = installReplayInterruptHandlers({
+    experimentId,
+    experimentUrl: fullExperimentUrl,
+    interrupt: interruptReplay,
+    onInterrupt: options?.onInterrupt
+  });
+  let completeReturned = false;
+  const markCompleteReturned = () => {
+    completeReturned = true;
+    void heartbeat.stop();
+  };
+  try {
+    return await runReplaySession(
+      httpClient,
+      fn,
+      session,
+      fullExperimentUrl,
+      maxConcurrency,
+      interruptHandlers.remove,
+      markCompleteReturned,
+      interruptHandlers.interrupted,
+      options,
+      registeredOverrides
+    );
+  } catch (error) {
+    if (!completeReturned && !interruptHandlers.interrupted()) {
+      await interruptReplay();
+    }
+    throw error;
+  } finally {
+    interruptHandlers.remove();
+    await heartbeat.stop();
+  }
+}
+function throwIfInterrupted(interrupted, items, experimentId, experimentUrl) {
+  if (!interrupted()) {
+    return;
+  }
+  const cause = new BitfabError(
+    `Experiment ${experimentId} was interrupted, so it was not completed or graded. Resume it by passing { resume: "${experimentId}" } to replay, or with bitfab-replay --resume ${experimentId}.`,
+    experimentUrl
+  );
+  throw new ReplayError(
+    cause.message,
+    items,
+    experimentId,
+    experimentUrl,
+    cause
+  );
+}
+async function runReplaySession(httpClient, fn, session, fullExperimentUrl, maxConcurrency, stopInterruptingOnSignal, markCompleteReturned, interrupted, options, registeredOverrides) {
+  const { experimentId, attempts } = session;
+  const mockStrategy = options?.mock ?? "marked";
+  if (experimentId !== null && fullExperimentUrl !== null) {
+    try {
+      options?.onExperimentStart?.({
+        experimentId,
+        experimentUrl: fullExperimentUrl
+      });
+    } catch {
+    }
+  }
+  const resolvedOverrides = [
+    ...normalizeMockOverrides(options?.mockOverride),
+    ...registeredOverrides
+  ];
+  const workItems = session.work;
+  const carriedOverItems = session.finished.map(
+    (finished) => carriedOverReplayItem(finished)
+  );
+  const replayedTraceIds = workItems.map(() => randomUuid());
+  httpClient.trackTraceDeliveries(replayedTraceIds);
+  const tasks = workItems.map(
+    ({ serverItem, attempt }, index) => () => processItem(
+      httpClient,
+      serverItem,
+      fn,
+      experimentId,
+      mockStrategy,
+      resolvedOverrides,
+      replayedTraceIds[index],
+      attempt,
+      session.includeDbBranchLease,
+      session.dbBranchSettings,
+      options?.adaptInputs,
+      options?.dryRun === true,
+      options?.experimentalSelectiveReplay
+    )
+  );
+  const total = tasks.length + carriedOverItems.length;
+  const onItemFinish = options?.onItemFinish ?? options?.onProgress;
+  let completed = carriedOverItems.length;
+  let started = carriedOverItems.length;
+  let errored = carriedOverItems.filter((item) => item.error !== null).length;
+  let succeeded = completed - errored;
+  let flushInFlight = null;
+  let flushPending = false;
+  const flushFinishedItemTrace = () => {
+    flushPending = true;
+    if (!flushInFlight) {
+      flushInFlight = (async () => {
+        try {
+          while (flushPending) {
+            flushPending = false;
+            await httpClient.settleDeferredWork(REPLAY_PERSISTENCE_TIMEOUT_MS);
+            await flushTraces(REPLAY_PERSISTENCE_TIMEOUT_MS);
+          }
+        } finally {
+          flushInFlight = null;
+        }
+      })();
+    }
+    return flushInFlight;
+  };
+  const ranItems = await mapWithConcurrency(
+    tasks,
+    maxConcurrency,
+    async (item, index) => {
+      let serverTraceId = null;
+      try {
+        await flushFinishedItemTrace();
+        serverTraceId = httpClient.peekServerTraceId(replayedTraceIds[index]) ?? null;
+      } catch {
+      }
+      item.traceId = serverTraceId;
+      completed += 1;
+      if (item.error === null) {
+        succeeded += 1;
+      } else {
+        errored += 1;
+      }
+      try {
+        onItemFinish?.({
+          experimentId,
+          testRunId: experimentId,
+          completed,
+          total,
+          succeeded,
+          errored,
+          item: {
+            // The server's assigned traces.id, read back off the ingest
+            // response and surfaced as this item finishes. Null only if the
+            // per-item flush could not confirm delivery in time; the end-of-run
+            // barrier then fills the returned ReplayItem. The client-side
+            // placeholder is never surfaced.
+            traceId: serverTraceId,
+            originalTraceId: item.originalTraceId ?? null,
+            originalSpanId: item.originalSpanId ?? null,
+            // Deprecated aliases for originalTraceId/originalSpanId.
+            sourceTraceId: item.originalTraceId ?? null,
+            sourceSpanId: item.originalSpanId ?? null,
+            attempt: item.attempt,
+            input: item.input,
+            result: item.result,
+            originalOutput: item.originalOutput,
+            error: item.error,
+            traceError: item.traceError,
+            replayError: item.replayError,
+            durationMs: item.durationMs,
+            ...item.selectiveReplay === void 0 ? {} : { selectiveReplay: item.selectiveReplay },
+            originalDurationMs: item.originalDurationMs,
+            originalTokens: item.originalTokens,
+            originalModel: item.originalModel,
+            ingestionType: item.ingestionType,
+            tokens: item.tokens,
+            model: item.model,
+            dbSnapshotRef: item.dbSnapshotRef,
+            dbBranchTimings: item.dbBranchTimings
+          }
+        });
+      } catch {
+      }
+    },
+    options?.onItemStart ? (index) => {
+      started += 1;
+      const { serverItem, attempt } = workItems[index];
+      const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
+      const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
+      try {
+        options.onItemStart?.({
+          type: "started",
+          experimentId,
+          testRunId: experimentId,
+          started,
+          completed,
+          total,
+          succeeded,
+          errored,
+          item: {
+            originalTraceId,
+            originalSpanId,
+            sourceTraceId: originalTraceId,
+            sourceSpanId: originalSpanId,
+            attempt
+          }
+        });
+      } catch {
+      }
+    } : void 0,
+    interrupted
+  );
+  const resultItems = [...carriedOverItems, ...ranItems];
+  if (options?.dryRun === true || experimentId === null || fullExperimentUrl === null) {
+    if (experimentId !== null && fullExperimentUrl !== null) {
+      throwIfInterrupted(
+        interrupted,
+        resultItems,
+        experimentId,
+        fullExperimentUrl
+      );
+      stopInterruptingOnSignal();
+      await httpClient.completeReplay(experimentId).catch(() => void 0);
+      markCompleteReturned();
+    }
+    const dryResult = {
+      items: resultItems,
+      experimentId,
+      experimentUrl: fullExperimentUrl,
+      testRunId: experimentId,
+      testRunUrl: fullExperimentUrl,
+      attempts
+    };
+    await writeReplayResultFile(dryResult);
+    return dryResult;
+  }
+  throwIfInterrupted(interrupted, resultItems, experimentId, fullExperimentUrl);
+  const deliveredTraceIds = await preserveReplayFailure(
+    () => waitForReplayPersistence(
+      httpClient,
+      experimentId,
+      replayedTraceIds,
+      Object.fromEntries(
+        workItems.map(({ serverItem, attempt }, index) => [
+          replayedTraceIds[index],
+          `${serverItem.originalTraceId ?? serverItem.sourceTraceId}#${attempt}`
+        ])
+      )
+    ),
+    resultItems,
+    experimentId,
+    fullExperimentUrl
+  );
+  for (let index = 0; index < ranItems.length; index += 1) {
+    const localId = replayedTraceIds[index];
+    const readBack = localId ? deliveredTraceIds[localId] : void 0;
+    if (readBack !== void 0) {
+      ranItems[index].traceId = readBack;
+    }
+  }
+  throwIfInterrupted(interrupted, resultItems, experimentId, fullExperimentUrl);
+  stopInterruptingOnSignal();
+  const completeResult = await preserveReplayFailure(
+    () => httpClient.completeReplay(experimentId),
+    resultItems,
+    experimentId,
+    fullExperimentUrl
+  );
+  markCompleteReturned();
+  const serverTraceIds = completeResult.traceIds;
+  const replayTokens = completeResult.tokens;
+  if (serverTraceIds !== void 0) {
+    const missing = [];
+    let completedCount = 0;
+    for (let index = 0; index < ranItems.length; index += 1) {
+      const item = ranItems[index];
+      const localId = replayedTraceIds[index];
+      const mapped = localId ? serverTraceIds[localId] : void 0;
+      item.traceId = item.traceId ?? mapped ?? null;
+      if (item.error === null) {
+        completedCount += 1;
+        if (mapped === void 0) {
+          missing.push(localId ?? item.originalTraceId);
+        }
+      }
+      if (mapped !== void 0) {
+        item.tokens = replayTokens?.[mapped] ?? null;
+      }
+    }
+    if (completedCount > 0 && missing.length === completedCount) {
+      const serverCount = completeResult.traceCount !== void 0 ? ` The server persisted ${completeResult.traceCount} trace(s) for this run.` : "";
+      const cause = new BitfabError(
+        `Replay completed but the server has no persisted trace for any of the ${completedCount} completed item(s) (experiment ${experimentId}).${serverCount} Trace uploads were awaited, so either the uploads failed (check for "Bitfab: Failed to create" errors above) or the replayed function is not wrapped with withSpan.`
+      );
+      throw new ReplayError(
+        cause.message,
+        resultItems,
+        experimentId,
+        fullExperimentUrl,
+        cause
+      );
+    }
+    if (missing.length > 0) {
+      try {
+        console.error(
+          `Bitfab: server has no persisted trace for ${missing.length} of ${completedCount} completed replay item(s) (experiment ${experimentId}). Their replay token usage is unavailable and they cannot be labeled.`
+        );
+      } catch {
+      }
+    }
+  }
+  const result = {
+    items: resultItems,
+    experimentId,
+    experimentUrl: fullExperimentUrl,
+    testRunId: experimentId,
+    testRunUrl: fullExperimentUrl,
+    attempts
+  };
+  await writeReplayResultFile(result);
+  if (!options?.onItemFinish) {
+    try {
+      options?.onProgress?.({
+        type: "complete",
+        experimentId,
+        testRunId: experimentId,
+        completed: total,
+        total,
+        succeeded,
+        errored,
+        result
+      });
+    } catch {
+    }
+  }
+  return result;
+}
+async function writeReplayResultFile(result) {
+  const resultPath = typeof process !== "undefined" ? process.env?.BITFAB_REPLAY_RESULT_PATH : void 0;
+  if (!resultPath) {
+    return;
+  }
+  try {
+    const [{ dirname }, { mkdir, writeFile }] = await Promise.all([
+      import("path"),
+      import("fs/promises")
+    ]);
+    await mkdir(dirname(resultPath), { recursive: true });
+    await writeFile(resultPath, `${serializeReplayResult(result)}
+`);
+  } catch (err) {
+    try {
+      console.warn(
+        `Bitfab: failed to write replay result to BITFAB_REPLAY_RESULT_PATH (${resultPath}): ${err instanceof Error ? err.message : String(err)}`
+      );
+    } catch {
+    }
+  }
+}
+
+export {
+  describeReplayInterrupt,
+  canonicalCliFlag,
+  withCliFlags,
+  BITFAB_PROGRESS_PREFIX,
+  reportReplayProgress,
+  ReplayError,
+  DbBranchReplayError,
+  serializeReplayResult,
+  deserializeInputs,
+  waitForReplayPersistence,
+  sleepForReplayPersistence,
+  JUDGE_ASSERTIONS_DEPRECATION_WARNING,
+  warnJudgeAssertionsDeprecated,
+  replay
+};
+//# sourceMappingURL=chunk-NGKTKRCV.js.map