@hue-run/sdk 0.11.4 → 0.12.0

package/dist/evals/runner.js

@@ -65,6 +65,36 @@ export class TargetCancelledError extends Error {
         this.name = "TargetCancelledError";
     }
 }
+/** Thrown by the environment target when the target did not return before its world's deadline.
+ * The world is sealed abandoned and the attempt saved as an `error` of type `TargetTimeout`, so a
+ * hung agent ends its case instead of holding the run open. */
+export class TargetTimeoutError extends Error {
+    environmentRunId;
+    expiresAt;
+    constructor(
+    /** The world whose deadline passed. */
+    environmentRunId, 
+    /** The world's `expiresAt`. */
+    expiresAt) {
+        super(`Target did not finish before its world ${environmentRunId} expired at ${expiresAt}`);
+        this.environmentRunId = environmentRunId;
+        this.expiresAt = expiresAt;
+        this.name = "TargetTimeoutError";
+    }
+}
+/** The target's outcome is saved but the telemetry it requires was never acknowledged on an
+ * earlier attempt. Restore or export the trace, or complete with omitted evidence through the
+ * client; the target is never rerun. It is this case's own state, not the run's. */
+export class TraceExportUnacknowledgedError extends Error {
+    executionId;
+    constructor(
+    /** The execution whose saved outcome waits for its trace. */
+    executionId) {
+        super("Target outcome is saved but trace export acknowledgement is unavailable. Restore/export the trace or explicitly complete with omitted evidence through the client; never rerun the target.");
+        this.executionId = executionId;
+        this.name = "TraceExportUnacknowledgedError";
+    }
+}
 /** Thrown when the target or world may have committed but acknowledgement is unavailable. */
 export class TargetOutcomeUncertainError extends Error {
     executionId;
@@ -177,25 +207,82 @@ async function allPages(page, maximum = 5000) {
     } while (after !== undefined);
     return items;
 }
+/** A failure the next case would meet too: Hue not answering or refusing (a transient failure
+ * past the client's retries, a lost connection, a refusal such as a finished experiment or a
+ * world that cannot be sealed), telemetry not accepted by the one transport the cases share, or
+ * a target outcome left uncertain because its world could not be sealed or read back. Starting
+ * more cases into it only piles up the same failure; the run is resumed later instead. */
+function systemic(error) {
+    // A saved outcome still waiting for its trace (`TraceExportUnacknowledgedError`) is not
+    // systemic: the flush failed on an earlier attempt, telemetry may have recovered since, and
+    // the cases beside it can complete now; only a live export failure stops new cases.
+    return (error instanceof HueApiError ||
+        error instanceof HueExportError ||
+        error instanceof TargetOutcomeUncertainError);
+}
+/** Runs every case, `concurrency` at a time. One case's own failure (an attempt without a saved
+ * outcome, an output that cannot be saved, inputs the SDK refuses) does not stop the cases
+ * beside or after it: each is attempted, and the failures are thrown together at the end, so a
+ * resume has only the failed cases left to publish. A systemic failure stops new cases from
+ * starting, while the cases in flight finish; the run resumes when Hue answers again. */
 async function pool(items, concurrency, execute) {
     let position = 0;
     const failures = [];
+    let stop = false;
     await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-        while (position < items.length && !failures.length) {
+        while (position < items.length && !stop) {
             const item = items[position++];
             try {
                 await execute(item);
             }
             catch (error) {
                 failures.push(error);
+                if (systemic(error))
+                    stop = true;
             }
         }
     }));
     if (failures.length === 1)
         throw failures[0];
-    if (failures.length)
-        throw new AggregateError(failures, "Multiple case operations failed; resume uses saved outcomes");
+    if (failures.length) {
+        const first = failures[0];
+        throw new AggregateError(failures, `${failures.length} case operations failed; resume uses saved outcomes. First: ${first instanceof Error ? first.message : String(first)}`);
+    }
 }
+/** Whether Hue holds the case's telemetry, read from the trace receipt: its root span and at
+ * least as many spans as the case ended; false when they are not there by the wait's end or the
+ * receipt cannot be read, and for a checkpoint an older runner saved without the span. */
+async function traceLanded(hue, trace) {
+    // Without the count of spans the case ended, the receipt cannot tell a lost child span from a
+    // landed trace, and does not accept.
+    if (!trace || trace.spans === undefined)
+        return false;
+    const deadline = Date.now() + RECEIPT_WAIT_MS;
+    try {
+        for (;;) {
+            // The root span present and every span the case ended held: a lost child span is not
+            // hidden behind a root that landed. The receipt answers as soon as the root is there, so
+            // spans still arriving behind it are polled for until the wait ends.
+            const verification = await hue.verifyTrace(trace.traceId, {
+                expectedSpanIds: [trace.spanId],
+                timeoutMillis: Math.max(250, deadline - Date.now()),
+            });
+            if (verification.verified && (verification.receipt?.spanCount ?? 0) >= trace.spans)
+                return true;
+            if (!verification.verified || Date.now() + RECEIPT_POLL_MS >= deadline)
+                return false;
+            await new Promise((resolve) => setTimeout(resolve, RECEIPT_POLL_MS));
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** How long a receipt is polled for the root span after a flush reported a failure: ingestion
+ * of an accepted batch is not instant, and a span that is not there by then was not delivered. */
+const RECEIPT_WAIT_MS = 5_000;
+/** How often the receipt is read again while the root is there but spans are still arriving. */
+const RECEIPT_POLL_MS = 500;
 async function scoresFor(versions, context, options, executionId, hasEnvironment = true) {
     const scores = [];
     let environmentUnavailable = false;
@@ -329,8 +416,14 @@ export async function runExperiment(options) {
     try {
         const filesRoot = resolve(options.filesDirectory ?? join(options.checkpointDirectory, "files"));
         const sanitize = (message) => message.slice(0, 4000).toWellFormed().replaceAll("\u0000", "");
+        // A target stopped at its world's deadline is a `TargetTimeout`, told apart from an error the
+        // target raised itself: the agent did not finish, rather than finishing wrongly.
         const errorPayload = (error) => ({
-            type: error instanceof OutputTooLargeError ? "OutputTooLarge" : "TargetError",
+            type: error instanceof OutputTooLargeError
+                ? "OutputTooLarge"
+                : error instanceof TargetTimeoutError
+                    ? "TargetTimeout"
+                    : "TargetError",
             ...(options.persistResultContent && error instanceof Error
                 ? { message: sanitize(error.message) }
                 : {}),
@@ -378,6 +471,7 @@ export async function runExperiment(options) {
                 complete,
                 scores,
                 exportState: "pending",
+                ...(saved.trace ? { trace: saved.trace } : {}),
             };
             await store.write(file, prepared);
             return prepared;
@@ -533,6 +627,7 @@ export async function runExperiment(options) {
                     const uploading = {
                         stage: "uploading",
                         executionId: execution.id,
+                        trace: { traceId: span.traceId, spanId: span.spanId },
                         state,
                         hasOutput: output !== undefined,
                         ...(options.persistResultContent && output !== undefined ? { output } : {}),
@@ -553,13 +648,50 @@ export async function runExperiment(options) {
                 // End root before waiting for both OTLP signals. Export failure leaves the prepared checkpoint intact.
                 let exportError;
                 try {
-                    await options.hue.flush();
-                    // Another concurrent flush may already have surfaced this failure. OTLP
-                    // partial acknowledgements do not identify individual rejected records.
-                    if (options.hue.transport.getFailureSequence() !== failureSequenceBefore)
-                        throw new HueExportError(options.hue.transport
-                            .getIssues()
-                            .filter((issue) => issue.sequence > failureSequenceBefore && issue.kind !== "warning"), options.hue.transport.getReport());
+                    // The flush itself throws for any failure since the last flush; the issues it recorded
+                    // are read below, where they are attributed.
+                    await options.hue.flush().catch((error) => {
+                        if (!(error instanceof HueExportError))
+                            throw error;
+                    });
+                    // The transport is shared by every case in flight, so a failure the flush reports may
+                    // be another case's. Each issue names the traces of the records it concerned: one that
+                    // names this trace is this case's failure, final because its evidence is incomplete;
+                    // one that names only others is not this case's; one that names no trace (a processor
+                    // flush that failed) may be anyone's, and this case's trace receipt decides: its root
+                    // span landed, or the case stays pending for the receipt to decide again on resume.
+                    const decided = checkpoint;
+                    const traceId = decided.trace?.traceId;
+                    // Every span the case ended has reached the exporter by now; the receipt is held to
+                    // that count, so a lost child span is not hidden behind a root span that landed. The
+                    // count is saved before anything is decided, so a process that stops here leaves a
+                    // pending checkpoint the receipt can be held to; a transport that does not count (an
+                    // older or borrowed one) leaves no count, and the receipt then cannot accept.
+                    if (decided.trace && traceId !== undefined) {
+                        const spans = options.hue.transport.spansEnded?.(traceId);
+                        if (spans !== undefined) {
+                            decided.trace.spans = spans;
+                            await store.write(file, decided);
+                        }
+                    }
+                    if (options.hue.transport.getFailureSequence() !== failureSequenceBefore) {
+                        const retained = options.hue.transport.getIssues();
+                        const issues = retained.filter((issue) => issue.sequence > failureSequenceBefore && issue.kind !== "warning");
+                        const named = issues.filter((issue) => issue.traceIds && (traceId === undefined || issue.traceIds.includes(traceId)));
+                        // An issue naming no trace, and a failure whose issue the bounded history has already
+                        // rolled past (the oldest retained issue is younger than the first this case could
+                        // have caused), may be anyone's.
+                        const unattributed = issues.filter((issue) => !issue.traceIds);
+                        const evicted = issues.length === 0 || (retained[0]?.sequence ?? 0) > failureSequenceBefore + 1;
+                        if (named.length) {
+                            checkpoint.exportState = "failed";
+                            await store.write(file, checkpoint);
+                            throw new HueExportError([...named, ...unattributed], options.hue.transport.getReport());
+                        }
+                        if ((unattributed.length || evicted) &&
+                            !(await traceLanded(options.hue, decided.trace)))
+                            throw new HueExportError(unattributed, options.hue.transport.getReport());
+                    }
                 }
                 catch (error) {
                     exportError = error;
@@ -606,8 +738,18 @@ export async function runExperiment(options) {
             }
             const prepared = checkpoint;
             await options.client.getExecution(prepared.executionId);
+            // A saved outcome no flush decided on is asked about through its trace receipt: the root
+            // span there says the case's export landed before the process stopped, or that a later
+            // flush of the same transport delivered it. An export failure that named this trace is
+            // final: the evidence is incomplete whatever the receipt holds.
+            if (prepared.exportState === "pending" &&
+                prepared.complete.traceEvidence !== "omit" &&
+                (await traceLanded(options.hue, prepared.trace))) {
+                prepared.exportState = "accepted";
+                await store.write(file, prepared);
+            }
             if (prepared.exportState !== "accepted" && prepared.complete.traceEvidence !== "omit")
-                throw new Error("Target outcome is saved but trace export acknowledgement is unavailable. Restore/export the trace or explicitly complete with omitted evidence through the client; never rerun the target.");
+                throw new TraceExportUnacknowledgedError(prepared.executionId);
             const save = () => store.write(file, prepared);
             const notAccepted = prepared.exportState === "not_accepted"
                 ? {

package/dist/evals.d.ts

@@ -1,6 +1,6 @@
-export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, } from "./evals/client.js";
+export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, isTransientApiError, } from "./evals/client.js";
 export type { EvaluationClientOptions } from "./evals/client.js";
-export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, } from "./evals/runner.js";
+export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError, TraceExportUnacknowledgedError, } from "./evals/runner.js";
 export type { RunExperimentOptions, RunExperimentTargetContext, RescoreOptions, RunnerReport, TelemetryIssueCount, TelemetryNotAccepted, } from "./evals/runner.js";
 export { TargetResult, withFiles } from "./evals/types.js";
 export { CaseFileError, outputContentTypes, outputFileLimits, OutputFileError, safeFilename, targetFileRoles, } from "./evals/files.js";
@@ -13,7 +13,7 @@ export { builtins, defineLocalScorer, scoreLocally } from "./evals/scorers.js";
 export { sourceDigest } from "./evals/json.js";
 export type * from "./evals/types.js";
 export { localAgentCapabilities, registeredCapabilities, runLocalAgent, } from "./evals/local-worker.js";
-export type { LocalAgentDirectContext, LocalAgentTargetContext, RunLocalAgentOptions, } from "./evals/local-worker.js";
+export type { LocalAgentDirectContext, LocalAgentTargetContext, LocalRunFailure, RunLocalAgentOptions, } from "./evals/local-worker.js";
 export { getScenario, listScenarios, matchByName, parseScenarioSelector, resolveEvalSetPins, resolveScenarioPins, } from "./evals/scenarios.js";
 export type { NamedCandidate, NameMatch, ScenarioClient, ScenarioPins, ScenarioSelector, } from "./evals/scenarios.js";
 export { collectExperimentVerdicts, compareVerdicts, metricPassed, summarizeVerdicts, waitForResults, } from "./evals/verdicts.js";

package/dist/evals.js

@@ -1,5 +1,5 @@
-export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, } from "./evals/client.js";
-export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, } from "./evals/runner.js";
+export { ArtifactSizeError, createEvaluationClient, EvaluationClient, HueApiError, isTransientApiError, } from "./evals/client.js";
+export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError, TraceExportUnacknowledgedError, } from "./evals/runner.js";
 export { TargetResult, withFiles } from "./evals/types.js";
 export { CaseFileError, outputContentTypes, outputFileLimits, OutputFileError, safeFilename, targetFileRoles, } from "./evals/files.js";
 export { runSimulation } from "./evals/simulation.js";

package/dist/transport.d.ts

@@ -75,6 +75,13 @@ export declare class HueTransport {
     getIssues(): ExportIssue[];
     /** Monotonic failure marker, retained even when the bounded issue history rolls over. */
     getFailureSequence(): number;
+    /** Spans of a trace this transport has handed to its exporter, by trace id, for the newest
+     * traces only: a runner compares the count with the trace receipt's span count to know that
+     * every span of a case landed, not only the root. Undefined for a trace it does not remember,
+     * which is not the same as none: the caller must not take an unknown count for complete. */
+    spansEnded(traceId: string): number | undefined;
+    private endedSpans;
+    private countEnded;
     /**
      * Waits for the processors' and exporters' in-flight work; drain the providers first.
      *

package/dist/transport.js

@@ -138,12 +138,13 @@ export class HueTransport {
                     if (!queued)
                         return;
                     admitted = queued;
+                    this.countEnded(admitted);
                     spans.onEnd(admitted);
                 }
                 catch {
                     if (admitted)
                         this.finish("traces", [admitted]);
-                    this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record");
+                    this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([span]));
                 }
             },
             forceFlush: () => spans.forceFlush(),
@@ -165,7 +166,7 @@ export class HueTransport {
                 catch {
                     if (admitted)
                         this.finish("logs", [admitted]);
-                    this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record");
+                    this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([log]));
                 }
             },
             forceFlush: () => logs.forceFlush(),
@@ -181,10 +182,13 @@ export class HueTransport {
         const pending = signal === "traces" ? this.spans : this.logs;
         if (advisory && (this.closed || pending.size >= 2048 / 4))
             return undefined;
+        // A record dropped here names its trace, so a runner with several traces in flight knows
+        // whose telemetry is missing; a log record names the trace of the span it was emitted in.
+        const traceIds = traceIdsOf([record]);
         if (this.closed || pending.size >= 2048) {
             this.issue(signal, "dropped", 1, this.closed
                 ? "Telemetry emitted after transport shutdown"
-                : "Telemetry queue reached 2048 records");
+                : "Telemetry queue reached 2048 records", undefined, traceIds);
             return undefined;
         }
         try {
@@ -205,7 +209,7 @@ export class HueTransport {
         catch {
             if (advisory)
                 return undefined;
-            this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data");
+            this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data", undefined, traceIds);
             return undefined;
         }
     }
@@ -299,7 +303,7 @@ export class HueTransport {
         this.accepted[signal] += count;
     }
     /** @internal Records a sanitized issue, updates counters and rate-limits the diagnostic callback. */
-    issue(signal, kind, count, message, status) {
+    issue(signal, kind, count, message, status, traceIds) {
         if (kind === "dropped")
             this.dropped[signal] += count;
         if (kind === "rejected")
@@ -313,6 +317,7 @@ export class HueTransport {
             count,
             message,
             ...(status !== undefined ? { status } : {}),
+            ...(traceIds !== undefined ? { traceIds } : {}),
         };
         if (kind !== "warning")
             this.failureSequence = issue.sequence;
@@ -339,11 +344,13 @@ export class HueTransport {
         }
     }
     /** @internal Counts a helper capture or instrumentation failure that preserved application execution. */
-    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved", count = 1) {
+    /** Records a capture or instrumentation failure, named to the trace it happened in when the
+     * caller knows it, so a runner with several traces in flight can tell whose it was. */
+    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved", count = 1, traceId) {
         if (!Number.isSafeInteger(count) || count < 1)
             return;
         this.instrumentationFailures += count;
-        this.issue(signal, "invalid", 0, message);
+        this.issue(signal, "invalid", 0, message, undefined, traceId ? [traceId] : undefined);
     }
     /** Cumulative counters and current queue gauges. */
     getReport() {
@@ -370,6 +377,26 @@ export class HueTransport {
     getFailureSequence() {
         return this.failureSequence;
     }
+    /** Spans of a trace this transport has handed to its exporter, by trace id, for the newest
+     * traces only: a runner compares the count with the trace receipt's span count to know that
+     * every span of a case landed, not only the root. Undefined for a trace it does not remember,
+     * which is not the same as none: the caller must not take an unknown count for complete. */
+    spansEnded(traceId) {
+        return this.endedSpans.get(traceId);
+    }
+    endedSpans = new Map();
+    countEnded(span) {
+        let traceId;
+        try {
+            traceId = span.spanContext().traceId;
+        }
+        catch {
+            return;
+        }
+        this.endedSpans.set(traceId, (this.endedSpans.get(traceId) ?? 0) + 1);
+        if (this.endedSpans.size > MAX_REMEMBERED_TRACES)
+            this.endedSpans.delete(this.endedSpans.keys().next().value);
+    }
     /**
      * Waits for the processors' and exporters' in-flight work; drain the providers first.
      *
@@ -427,6 +454,32 @@ export class HueTransport {
         return this.shutdownPromise;
     }
 }
+/** The distinct trace ids of a batch, or undefined past 64 of them, when an issue would name too
+ * many traces to tell one apart; a record whose context cannot be read is left out. */
+const MAX_ISSUE_TRACE_IDS = 64;
+/** How many traces' ended-span counts one transport remembers; the oldest is forgotten first. */
+const MAX_REMEMBERED_TRACES = 10_000;
+function traceIdsOf(records) {
+    const ids = new Set();
+    for (const record of records) {
+        try {
+            // A span reports its context; a log record carries the span's identifiers.
+            const traceId = "spanContext" in record && typeof record.spanContext === "function"
+                ? record.spanContext().traceId
+                : record.spanContext?.traceId;
+            if (traceId)
+                ids.add(traceId);
+        }
+        catch {
+            // A record without a readable context names no trace.
+        }
+        if (ids.size > MAX_ISSUE_TRACE_IDS)
+            return undefined;
+    }
+    // No readable trace names nobody, which is not the same as naming no one's: the issue may
+    // concern any trace in flight.
+    return ids.size ? [...ids] : undefined;
+}
 class ReportingExporter {
     transport;
     signal;
@@ -485,12 +538,12 @@ class ReportingExporter {
         const cache = new WeakMap();
         let failed = false;
         let redactedBytes = 0;
-        const invalid = (placeholder, message) => {
+        const invalid = (placeholder, message, record) => {
             if (placeholder)
                 this.transport.issue(this.signal, "warning", 1, `${message} (in-progress span placeholder)`);
             else {
                 failed = true;
-                this.transport.issue(this.signal, "invalid", 1, message);
+                this.transport.issue(this.signal, "invalid", 1, message, undefined, record ? traceIdsOf([record]) : undefined);
             }
         };
         const send = async (batch) => {
@@ -539,7 +592,7 @@ class ReportingExporter {
                     placeholders.add(redacted);
             }
             catch {
-                invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits");
+                invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
             }
         }
         // Each record is encoded once to measure it; a request is encoded once more when it is sent.
@@ -555,7 +608,7 @@ class ReportingExporter {
                 recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
             }
             catch {
-                invalid(placeholders.has(record), "Telemetry record could not be serialized");
+                invalid(placeholders.has(record), "Telemetry record could not be serialized", record);
                 continue;
             }
             const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
@@ -565,7 +618,7 @@ class ReportingExporter {
                 batchBytes = 0;
             }
             if (recordBytes > limit) {
-                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit");
+                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit", record);
                 continue;
             }
             batch.push(record);
@@ -580,9 +633,12 @@ class ReportingExporter {
     async send(records, placeholders = 0) {
         const options = this.transport.options;
         const real = records.length - placeholders;
+        // The traces this batch carries, spans or the log records emitted in their spans, so a loss
+        // or rejection names whose telemetry it was.
+        const traceIds = traceIdsOf(records);
         // A loss involving only placeholders is a warning. Mixed losses count only real records.
         const lose = (message, status) => {
-            this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status);
+            this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status, traceIds);
             return !real;
         };
         let rejected = 0;
@@ -611,14 +667,19 @@ class ReportingExporter {
                     if (downgrade)
                         this.transport.rejectPlaceholders(placeholderRejections);
                     const remaining = count - placeholderRejections;
-                    // Rejections are not matched to records. Attribute them to real records first.
+                    // Rejections are not matched to records. Attribute them to real records first. A
+                    // rejection of spans in a batch of one trace is that trace's; in a batch of several it
+                    // names none, since the innocent traces' spans may have been accepted, and each case's
+                    // receipt decides. A rejection of log records names every trace in the batch: the
+                    // receipt counts spans, not logs, so it could not tell whose logs were lost.
                     rejected = Math.min(remaining, real);
+                    const rejectedTraceIds = this.signal === "logs" || (traceIds && traceIds.length === 1) ? traceIds : undefined;
                     if (remaining || (partial?.errorMessage && !downgrade))
                         this.transport.issue(this.signal, rejected ? "rejected" : "warning", rejected || remaining, rejected
                             ? "Hue rejected telemetry records; inspect the project ingestion settings and supported limits"
                             : remaining
                                 ? "Hue rejected in-progress span placeholders"
-                                : "Hue returned an ingestion warning");
+                                : "Hue returned an ingestion warning", undefined, rejectedTraceIds);
                     // Do not pass backend error text or raw response bytes into the global OTel diagnostic logger.
                     return {};
                 }

package/dist/types.d.ts

@@ -87,6 +87,13 @@ export interface ExportIssue {
     status?: number;
     /** Fixed, sanitized description; never server text or content. */
     message: string;
+    /** The traces the records concerned belonged to, when the issue arose with records in hand
+     * (a refused or rejected batch, a dropped record, a record the processor could not accept, a
+     * capture failure inside a span): up to 64 distinct ids, so a caller running several traces
+     * at once can tell whose telemetry the issue was. Absent for an issue without records (a
+     * processor flush that failed) and for a batch of more traces than that; such an issue may
+     * concern any trace in flight. */
+    traceIds?: string[];
 }
 /** Cumulative delivery counters and current queue gauges for one transport. */
 export interface ExportReport {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.11.4";
+export declare const sdkVersion = "0.12.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.11.4";
+export const sdkVersion = "0.12.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "private": false,
   "license": "MIT",
   "publishConfig": {