@bitfab/sdk 0.52.0 → 0.52.2

package/dist/index.d.cts

@@ -536,7 +536,7 @@ declare class HttpClient {
      * {@link HttpClient.sendExternalSpan}; replay confirms persistence with the
      * server-authoritative barrier in `replay.ts`, not by awaiting this call.
      */
-    sendExternalTrace(payload: Record<string, unknown>): void;
+    sendExternalTrace(rawPayload: Record<string, unknown>): void;
     /**
      * Partial update of an existing trace identified by its Bitfab trace ID.
      * Used by the detached `client.getTrace(id)` handle.
@@ -1656,12 +1656,16 @@ interface ReplayOptions {
      * Maximum number of traces to replay (1-5,000, default 5). Ignored when
      * `traceIds` is passed (with a warning), or when `datasetId` / `datasetIds`
      * is passed, because either source already determines how many traces replay.
+     * To replay part of a dataset selection, name the members to run in
+     * `traceIds` rather than bounding it here.
      */
     limit?: number;
     attempts?: number;
     /**
-     * Optional list of specific trace IDs to replay (max 100). Mutually exclusive
-     * with `datasetId` and `datasetIds`.
+     * Optional list of specific trace IDs to replay (max 100). Passed alongside
+     * `datasetId` or `datasetIds` it pins which members of that selection replay,
+     * and the server rejects any ID none of those datasets contains. On its own
+     * it selects by ID with no dataset attribution.
      */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
@@ -1719,8 +1723,9 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. Mutually exclusive with `traceIds` and
-     * with `datasetIds`. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `datasetIds`.
+     * Alone it replays the dataset's full membership, and with `traceIds` it
+     * replays only those members. When set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -3288,7 +3293,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.52.0";
+declare const __version__ = "0.52.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.d.ts

@@ -536,7 +536,7 @@ declare class HttpClient {
      * {@link HttpClient.sendExternalSpan}; replay confirms persistence with the
      * server-authoritative barrier in `replay.ts`, not by awaiting this call.
      */
-    sendExternalTrace(payload: Record<string, unknown>): void;
+    sendExternalTrace(rawPayload: Record<string, unknown>): void;
     /**
      * Partial update of an existing trace identified by its Bitfab trace ID.
      * Used by the detached `client.getTrace(id)` handle.
@@ -1656,12 +1656,16 @@ interface ReplayOptions {
      * Maximum number of traces to replay (1-5,000, default 5). Ignored when
      * `traceIds` is passed (with a warning), or when `datasetId` / `datasetIds`
      * is passed, because either source already determines how many traces replay.
+     * To replay part of a dataset selection, name the members to run in
+     * `traceIds` rather than bounding it here.
      */
     limit?: number;
     attempts?: number;
     /**
-     * Optional list of specific trace IDs to replay (max 100). Mutually exclusive
-     * with `datasetId` and `datasetIds`.
+     * Optional list of specific trace IDs to replay (max 100). Passed alongside
+     * `datasetId` or `datasetIds` it pins which members of that selection replay,
+     * and the server rejects any ID none of those datasets contains. On its own
+     * it selects by ID with no dataset attribution.
      */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
@@ -1719,8 +1723,9 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. Mutually exclusive with `traceIds` and
-     * with `datasetIds`. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `datasetIds`.
+     * Alone it replays the dataset's full membership, and with `traceIds` it
+     * replays only those members. When set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -3288,7 +3293,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.52.0";
+declare const __version__ = "0.52.2";
 
 /**
  * Constants for the Bitfab SDK.

package/dist/index.js

@@ -18,7 +18,7 @@ import {
   getCurrentSpan,
   getCurrentTrace,
   seedFromRegistry
-} from "./chunk-VEDTNQQE.js";
+} from "./chunk-XLSKI7UA.js";
 import "./chunk-ZUD7OFYB.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -27,7 +27,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-SJ65MW4K.js";
+} from "./chunk-XXKM4EL2.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -35,7 +35,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-4EOEBN3M.js";
+} from "./chunk-QWAWERYM.js";
 import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,

package/dist/node.cjs

@@ -88,7 +88,7 @@ var __version__, __packageName__;
 var init_version_generated = __esm({
   "src/version.generated.ts"() {
     "use strict";
-    __version__ = "0.52.0";
+    __version__ = "0.52.2";
     __packageName__ = "@bitfab/sdk";
   }
 });
@@ -541,6 +541,69 @@ var init_serializePayload = __esm({
   }
 });
 
+// src/traceMetadata.ts
+function recordCallerTraceMetadata(traceId, metadata) {
+  if (typeof traceId !== "string" || traceId === "") {
+    return;
+  }
+  if (typeof metadata !== "object" || metadata === null) {
+    return;
+  }
+  if (Object.keys(metadata).length === 0) {
+    return;
+  }
+  callerMetadata.set(traceId, { ...callerMetadata.get(traceId), ...metadata });
+}
+function callerTraceMetadata(traceId) {
+  const recorded = callerMetadata.get(traceId);
+  return recorded ? { ...recorded } : void 0;
+}
+function forgetTraceMetadata(traceId) {
+  callerMetadata.delete(traceId);
+  derivedMetadata.delete(traceId);
+}
+function mergeCallerMetadataIntoTracePayload(payload) {
+  const externalTrace = payload.externalTrace;
+  if (typeof externalTrace !== "object" || externalTrace === null) {
+    return payload;
+  }
+  const external = externalTrace;
+  const traceId = typeof payload.id === "string" && payload.id !== "" ? payload.id : external.id;
+  if (typeof traceId !== "string" || traceId === "") {
+    return payload;
+  }
+  const caller = callerMetadata.get(traceId);
+  if (!caller) {
+    return payload;
+  }
+  const derived = derivedMetadata.get(traceId) ?? {};
+  const exported = external.metadata;
+  if (typeof exported === "object" && exported !== null) {
+    Object.assign(derived, exported);
+  }
+  derivedMetadata.set(traceId, derived);
+  const shadowed = Object.keys(derived).filter((key) => key in caller && caller[key] !== derived[key]).sort();
+  if (shadowed.length > 0) {
+    warnOnce(
+      `trace-metadata-shadowed:${shadowed.join(",")}`,
+      `trace metadata key(s) ${shadowed.join(", ")} were set both by the caller and by an integration's own trace export; the caller's value is the one kept on the trace.`
+    );
+  }
+  return {
+    ...payload,
+    externalTrace: { ...external, metadata: { ...derived, ...caller } }
+  };
+}
+var callerMetadata, derivedMetadata;
+var init_traceMetadata = __esm({
+  "src/traceMetadata.ts"() {
+    "use strict";
+    init_warnOnce();
+    callerMetadata = /* @__PURE__ */ new Map();
+    derivedMetadata = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/transportTypes.ts
 var DeliveryError;
 var init_transportTypes = __esm({
@@ -1359,6 +1422,7 @@ var init_http = __esm({
     init_errors();
     init_replayContext();
     init_serializePayload();
+    init_traceMetadata();
     init_transport();
     init_transportTypes();
     init_unrefTimer();
@@ -1822,7 +1886,8 @@ var init_http = __esm({
        * {@link HttpClient.sendExternalSpan}; replay confirms persistence with the
        * server-authoritative barrier in `replay.ts`, not by awaiting this call.
        */
-      sendExternalTrace(payload) {
+      sendExternalTrace(rawPayload) {
+        const payload = mergeCallerMetadataIntoTracePayload(rawPayload);
         this.getTraceTransport()?.submit(
           "external_trace",
           {
@@ -2935,11 +3000,6 @@ async function replay(httpClient, serviceUrl, traceFunctionKey, fn, options, reg
     }
   }
   const datasetIds = resolveDatasetIds(options);
-  if (options?.traceIds !== void 0 && datasetIds !== void 0) {
-    throw new BitfabError(
-      "traceIds and datasetIds select different replay sources and cannot be used together."
-    );
-  }
   if (options?.limit !== void 0 && options?.traceIds !== void 0) {
     try {
       console.warn(
@@ -5714,6 +5774,7 @@ function runWithSeedContext(ctx, fn) {
 
 // src/client.ts
 init_serialize();
+init_traceMetadata();
 
 // src/tracing.ts
 init_constants();
@@ -6394,8 +6455,7 @@ function getCurrentTrace() {
         if (typeof metadata !== "object" || metadata === null) {
           return;
         }
-        const traceState = getOrCreateTraceState();
-        traceState.metadata = { ...traceState.metadata, ...metadata };
+        recordCallerTraceMetadata(traceId, metadata);
       } catch {
       }
     },
@@ -7388,7 +7448,7 @@ var Bitfab = class {
                 endedAt,
                 sessionId: traceState?.sessionId,
                 name: traceState?.name,
-                metadata: traceState?.metadata,
+                metadata: callerTraceMetadata(traceId),
                 contexts: traceState?.contexts ?? [],
                 testRunId: traceState?.testRunId,
                 inputSourceTraceId: traceState?.inputSourceTraceId,
@@ -7412,6 +7472,7 @@ var Bitfab = class {
                 }
               });
               activeTraceStates.delete(traceId);
+              forgetTraceMetadata(traceId);
             }
           } catch {
           }
@@ -7604,6 +7665,7 @@ var Bitfab = class {
       } catch (setupError) {
         if (registeredTraceId) {
           activeTraceStates.delete(registeredTraceId);
+          forgetTraceMetadata(registeredTraceId);
         }
         if (setupError instanceof MixedTracingError) {
           throw setupError;
@@ -7964,14 +8026,16 @@ var Bitfab = class {
     }
     const traceId = randomUuid();
     const startedAt = nowIsoTimestamp();
+    if (options.metadata !== void 0) {
+      recordCallerTraceMetadata(traceId, options.metadata);
+    }
     activeTraceStates.set(traceId, {
       traceId,
       startedAt,
       contexts: [],
       ingestionType: "seeded",
       ...options.sessionId !== void 0 && { sessionId: options.sessionId },
-      ...options.name !== void 0 && { name: options.name },
-      ...options.metadata !== void 0 && { metadata: options.metadata }
+      ...options.name !== void 0 && { name: options.name }
     });
     try {
       this.sendWrapperSpan({
@@ -7994,12 +8058,13 @@ var Bitfab = class {
         endedAt: startedAt,
         sessionId: options.sessionId,
         name: options.name,
-        metadata: options.metadata,
+        metadata: callerTraceMetadata(traceId),
         contexts: [],
         ingestionType: "seeded"
       });
     } finally {
       activeTraceStates.delete(traceId);
+      forgetTraceMetadata(traceId);
     }
     return traceId;
   }
@@ -8024,14 +8089,16 @@ var Bitfab = class {
     }
     await seedContextReady;
     const traceId = randomUuid();
+    if (options?.metadata !== void 0) {
+      recordCallerTraceMetadata(traceId, options.metadata);
+    }
     activeTraceStates.set(traceId, {
       traceId,
       startedAt: nowIsoTimestamp(),
       contexts: [],
       ingestionType: "seeded",
       ...options?.sessionId !== void 0 && { sessionId: options.sessionId },
-      ...options?.name !== void 0 && { name: options.name },
-      ...options?.metadata !== void 0 && { metadata: options.metadata }
+      ...options?.name !== void 0 && { name: options.name }
     });
     const args = options?.args ?? [];
     let unrecorded = true;
@@ -8043,6 +8110,7 @@ var Bitfab = class {
         await flushTraces2(3e4);
       } finally {
         unrecorded = activeTraceStates.delete(traceId);
+        forgetTraceMetadata(traceId);
       }
     }
     if (unrecorded) {