@bitfab/sdk 0.61.1 → 0.61.3

package/dist/index.cjs

@@ -42,7 +42,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.61.1";
+    __version__ = "0.61.3";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -1068,6 +1068,7 @@ var init_simulationPlan = __esm({
       "input_meta",
       "output",
       "output_meta",
+      "replay_recording",
       "prompt"
     ];
     SimulationPlan = class {
@@ -2882,8 +2883,11 @@ var init_http = __esm({
        * Start a replay session by fetching historical traces.
        * Blocking call - creates an experiment and returns lightweight item references.
        */
-      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetIds, graderIds, dbBranchSettings, attempts, includeOriginalMetadata, onlyWithAssertions, judgeAssertions) {
+      async startReplay(traceFunctionKey, limit, traceIds, name, codeChangeDescription, codeChangeFiles, includeDbBranchLease, experimentGroupId, datasetIds, graderIds, dbBranchSettings, attempts, includeOriginalMetadata, onlyWithAssertions, judgeAssertions, experimentalSelectiveReplay) {
         const payload = { traceFunctionKey };
+        if (experimentalSelectiveReplay !== void 0) {
+          payload.experimentalSelectiveReplay = experimentalSelectiveReplay;
+        }
         if (limit !== void 0) {
           payload.limit = limit;
         }
@@ -2951,6 +2955,46 @@ var init_http = __esm({
         }
         return { ...rest, experimentId, experimentUrl };
       }
+      async resumeReplay(experimentId, traceFunctionKey, codeChangeFiles, force) {
+        const payload = {
+          experimentId,
+          traceFunctionKey,
+          lazyDbBranchLease: true
+        };
+        if (force === true) {
+          payload.force = true;
+        }
+        if (codeChangeFiles !== void 0) {
+          payload.codeChangeFiles = codeChangeFiles;
+        }
+        const git = await resolvedGitState();
+        if (git && !isEmptyGitState(git)) {
+          payload.git = git;
+        }
+        const response = await this.request(
+          "/api/sdk/replay/resume",
+          payload,
+          { timeout: REPLAY_DB_BRANCH_REQUEST_TIMEOUT_MS }
+        );
+        const { testRunId, testRunUrl, ...rest } = response;
+        const resumedExperimentId = response.experimentId ?? testRunId;
+        const experimentUrl = response.experimentUrl ?? testRunUrl;
+        if (resumedExperimentId === void 0 || experimentUrl === void 0) {
+          throw new BitfabError(
+            "Replay resume response is missing the experiment ID or URL."
+          );
+        }
+        return {
+          ...rest,
+          experimentId: resumedExperimentId,
+          experimentUrl,
+          work: rest.work ?? [],
+          finished: rest.finished ?? [],
+          skippedOriginalTraceIds: rest.skippedOriginalTraceIds ?? [],
+          includeDbBranchLease: rest.includeDbBranchLease ?? false,
+          dbBranchSettings: rest.dbBranchSettings ?? null
+        };
+      }
       /**
        * Fetch an external span by ID.
        * Blocking GET request.
@@ -3567,6 +3611,291 @@ var init_integrationFixture = __esm({
   }
 });
 
+// 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;
+  }
+}
+var init_selectiveReplay = __esm({
+  "src/selectiveReplay.ts"() {
+    "use strict";
+  }
+});
+
+// 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;
+var init_selectiveReplayRuntime = __esm({
+  "src/selectiveReplayRuntime.ts"() {
+    "use strict";
+    init_errors();
+    init_selectiveReplay();
+    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 || (requiredByManifest = this.required.has(replayNodeKey(parent)));
+            requiredForAssertion || (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_exports = {};
 __export(replay_exports, {
@@ -3586,6 +3915,88 @@ function expandReplayWork(serverItems, attempts) {
     (_, attempt) => serverItems.map((serverItem) => ({ serverItem, attempt }))
   ).flat();
 }
+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,
+    traceOutline: null,
+    originalTraceOutline: null,
+    carriedOver: true
+  };
+}
 function resolveAttempts(attempts) {
   if (attempts === void 0) {
     return 1;
@@ -3740,7 +4151,7 @@ function buildMockTree(rootNode) {
   }
   return { spans };
 }
-async function processItem(httpClient, serverItem, fn, experimentId, mockStrategy, resolvedOverrides, replayedTraceId, attempt, includeDbBranchLease, dbBranchSettings, adaptInputs, dryRun) {
+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;
@@ -3753,6 +4164,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
   let replayError = null;
   let replayDurationMs = null;
   let replayStarted = null;
+  let selectiveReplay;
   const originalTraceId = serverItem.originalTraceId ?? serverItem.sourceTraceId;
   const originalSpanId = serverItem.originalSpanId ?? serverItem.sourceSpanId;
   try {
@@ -3785,6 +4197,17 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
         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"
     });
@@ -3804,7 +4227,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
       });
     }
     const hasOverrides = resolvedOverrides.length > 0;
-    const needTree = mockStrategy === "all" || mockStrategy === "marked" || hasOverrides;
+    const needTree = selectiveReplay === void 0 && (mockStrategy === "all" || mockStrategy === "marked" || hasOverrides);
     const includeOutputs = mockStrategy === "all";
     let mockTree;
     if (needTree) {
@@ -3879,6 +4302,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
           sourceBitfabTraceId: originalTraceId,
           replayAttempt: attempt,
           mockTree,
+          selectiveReplay,
           callCounters: mockTree ? /* @__PURE__ */ new Map() : void 0,
           mockStrategy,
           mockOverrides: hasOverrides ? resolvedOverrides : void 0,
@@ -3890,6 +4314,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
         () => fn(...inputs)
       );
       result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
+      selectiveReplay?.assertNoSafetyConflict();
       replayDurationMs = Math.round(performance.now() - replayStarted);
     } catch (e) {
       if (replayStarted !== null) {
@@ -3941,6 +4366,7 @@ async function processItem(httpClient, serverItem, fn, experimentId, mockStrateg
     traceError,
     replayError,
     durationMs: replayDurationMs,
+    ...selectiveReplay === void 0 ? {} : { selectiveReplay: selectiveReplay.report() },
     originalDurationMs,
     originalTokens: serverItem.originalTokens ?? serverItem.tokens ?? null,
     originalModel,
@@ -4038,6 +4464,21 @@ async function mapWithConcurrency2(tasks, maxConcurrency, onSettled, onStarted)
   return results;
 }
 async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, registeredOverrides = []) {
+  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.");
@@ -4057,7 +4498,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     } catch {
     }
   }
-  const attempts = resolveAttempts(options?.attempts);
+  const requestedAttempts = resolveAttempts(options?.attempts);
   const maxConcurrency = options?.maxConcurrency ?? 10;
   if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1) {
     throw new BitfabError(
@@ -4076,40 +4517,60 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     }
   }
-  const {
-    experimentId,
-    experimentUrl,
-    items: serverItems
-  } = 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.
-    dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
-    options?.experimentGroupId,
-    datasetIds,
-    options?.graderIds,
-    resolveDbBranchSettings(options?.dbBranch),
-    attempts,
-    options?.adaptInputs !== void 0,
-    options?.onlyWithAssertions,
-    options?.judgeAssertions
-  );
-  if (serverItems.length === 0) {
-    try {
-      console.warn(
-        `Bitfab: no traces matched "${traceFunctionKey}", so this replay ran nothing. Capture a trace, or seed one with seedTrace, before replaying.`
-      );
-    } catch {
+  const includeDbBranchLease = dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true;
+  let session;
+  if (options?.resume === void 0) {
+    const started2 = 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?.judgeAssertions,
+      options?.experimentalSelectiveReplay
+    );
+    if (started2.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: started2.experimentId,
+      experimentUrl: started2.experimentUrl,
+      attempts: requestedAttempts,
+      work: expandReplayWork(started2.items, requestedAttempts),
+      finished: [],
+      includeDbBranchLease,
+      dbBranchSettings: resolveDbBranchSettings(options?.dbBranch)
+    };
+  } else {
+    session = await resumeReplaySession(
+      httpClient,
+      options.resume,
+      traceFunctionKey,
+      codeChangeFiles,
+      options.force,
+      options.dbBranch
+    );
   }
+  const { experimentId, experimentUrl, attempts } = session;
   const mockStrategy = options?.mock ?? "marked";
   const fullExperimentUrl = `${serviceUrl}${experimentUrl}`;
   try {
@@ -4123,7 +4584,10 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     ...normalizeMockOverrides(options?.mockOverride),
     ...registeredOverrides
   ];
-  const workItems = expandReplayWork(serverItems, attempts);
+  const workItems = session.work;
+  const carriedOverItems = session.finished.map(
+    (finished) => carriedOverReplayItem(finished)
+  );
   const replayedTraceIds = workItems.map(() => randomUuid());
   httpClient.trackTraceDeliveries(replayedTraceIds);
   const tasks = workItems.map(
@@ -4136,18 +4600,19 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       resolvedOverrides,
       replayedTraceIds[index],
       attempt,
-      dbBranchEnabled(options?.dbBranch) && options?.dryRun !== true,
-      resolveDbBranchSettings(options?.dbBranch),
+      session.includeDbBranchLease,
+      session.dbBranchSettings,
       options?.adaptInputs,
-      options?.dryRun === true
+      options?.dryRun === true,
+      options?.experimentalSelectiveReplay
     )
   );
-  const total = tasks.length;
+  const total = tasks.length + carriedOverItems.length;
   const onItemFinish = options?.onItemFinish ?? options?.onProgress;
-  let completed = 0;
-  let started = 0;
-  let succeeded = 0;
-  let errored = 0;
+  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 = () => {
@@ -4167,7 +4632,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
     return flushInFlight;
   };
-  const resultItems = await mapWithConcurrency2(
+  const ranItems = await mapWithConcurrency2(
     tasks,
     maxConcurrency,
     async (item, index) => {
@@ -4212,6 +4677,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
             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,
@@ -4254,6 +4720,7 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
       }
     } : void 0
   );
+  const resultItems = [...carriedOverItems, ...ranItems];
   if (options?.dryRun === true) {
     await httpClient.completeReplay(experimentId).catch(() => void 0);
     const dryResult = {
@@ -4273,11 +4740,11 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     experimentId,
     fullExperimentUrl
   );
-  for (let index = 0; index < resultItems.length; index += 1) {
+  for (let index = 0; index < ranItems.length; index += 1) {
     const localId = replayedTraceIds[index];
     const readBack = localId ? deliveredTraceIds[localId] : void 0;
     if (readBack !== void 0) {
-      resultItems[index].traceId = readBack;
+      ranItems[index].traceId = readBack;
     }
   }
   const completeResult = await preserveReplayFailure(
@@ -4291,8 +4758,8 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
   if (serverTraceIds !== void 0) {
     const missing = [];
     let completedCount = 0;
-    for (let index = 0; index < resultItems.length; index += 1) {
-      const item = resultItems[index];
+    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;
@@ -4378,7 +4845,7 @@ async function writeReplayResultFile(result) {
     }
   }
 }
-var REPLAY_PERSISTENCE_TIMEOUT_MS, MAX_REPLAY_ATTEMPTS, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
+var REPLAY_PERSISTENCE_TIMEOUT_MS, MAX_REPLAY_ATTEMPTS, RESUME_CONFLICTING_OPTIONS, CARRIED_OVER_ERROR, BITFAB_PROGRESS_PREFIX, ReplayError, DbBranchReplayError;
 var init_replay = __esm({
   "src/replay.ts"() {
     "use strict";
@@ -4389,9 +4856,22 @@ var init_replay = __esm({
     init_mockOverride();
     init_randomUuid();
     init_replayContext();
+    init_selectiveReplayRuntime();
     init_serialize();
     REPLAY_PERSISTENCE_TIMEOUT_MS = 3e4;
     MAX_REPLAY_ATTEMPTS = 100;
+    RESUME_CONFLICTING_OPTIONS = [
+      "traceIds",
+      "limit",
+      "datasetId",
+      "datasetIds",
+      "attempts",
+      "graderIds",
+      "onlyWithAssertions",
+      "dryRun",
+      "experimentalSelectiveReplay"
+    ];
+    CARRIED_OVER_ERROR = "This item errored in an earlier run of this experiment, before it was resumed.";
     BITFAB_PROGRESS_PREFIX = "@@bitfab:progress ";
     ReplayError = class extends BitfabError {
       constructor(message, items, experimentId, experimentUrl, cause) {
@@ -9083,6 +9563,9 @@ var Bitfab = class {
       ...options.mockOnReplay !== void 0 && {
         mockOnReplay: options.mockOnReplay
       },
+      ...options.replayReusable !== void 0 && {
+        replayReusable: options.replayReusable
+      },
       ...options.finalize !== void 0 && { finalize: options.finalize }
     };
   }
@@ -9231,6 +9714,9 @@ var Bitfab = class {
               ...mockOnReplay !== void 0 && {
                 mockOnReplay
               },
+              ...nodeConfiguration?.replayReusable !== void 0 && {
+                replayReusable: nodeConfiguration.replayReusable
+              },
               ...nodeConfiguration?.finalize !== void 0 && {
                 finalize: nodeConfiguration.finalize
               }
@@ -10028,6 +10514,7 @@ var Bitfab = class {
           instrumentation: options.instrumentation ?? "span",
           functionId: options.functionId,
           captureContent: options.captureContent ?? true,
+          replayReusable: options.replayReusable,
           autoTraceDefinition: options.autoTraceDefinition,
           declaredNode: options.declaredNode === true,
           nestedTrace: options.nestedTrace,
@@ -10147,6 +10634,27 @@ var Bitfab = class {
           return result;
         };
         const replayCtxForMock = getReplayContext();
+        if (replayCtxForMock?.selectiveReplay) {
+          const decision = replayCtxForMock.selectiveReplay.enter({
+            traceFunctionKey,
+            spanName: baseSpanParams.spanName ?? traceFunctionKey,
+            spanId,
+            parentSpanId,
+            inputs: args,
+            safetyMock: !isRootSpan && options.mockOnReplay === true,
+            reuseAllowed: options.replayReusable === true,
+            canReuseOutput: options.finalize === void 0 && options.replayOutput === void 0 && !fn.constructor.name.includes("Generator")
+          });
+          if (decision.mock) {
+            void sendSpan({
+              result: decision.output,
+              mocked: true,
+              mockTarget: "output",
+              mockSource: "recorded"
+            });
+            return fnReturnsPromise ? Promise.resolve(decision.output) : decision.output;
+          }
+        }
         if (replayCtxForMock?.mockTree && !isRootSpan) {
           const counters = replayCtxForMock.callCounters;
           const counterKey = `${traceFunctionKey}:${baseSpanParams.spanName}`;
@@ -10570,6 +11078,9 @@ var Bitfab = class {
       span_origin: makeSpanOrigin(params.instrumentation),
       span_data: {
         name: params.spanName,
+        ...params.replayReusable !== void 0 && {
+          replay_reusable: params.replayReusable
+        },
         type: params.spanType,
         ...params.functionId !== void 0 && {
           function_id: params.functionId,