@hue-run/sdk 0.21.1 → 0.23.0

package/dist/cli/traces-import-prepare.d.ts

@@ -1,15 +1,20 @@
-import { type TraceImportFormat, type TraceImportManifest, type TraceImportOrigin, type TraceImportTotals } from "./traces-import-convert.js";
+import type { IdentityKeys } from "./import-formats/identity.js";
+import { type ReadResult } from "./import-formats/reader.js";
+import { type TraceImportManifest, type TraceImportOrigin, type TraceImportTotals } from "./traces-import-convert.js";
 /**
  * `hue traces import prepare`: reads a file, a directory or a ZIP archive, converts every trace
- * it recognizes and writes the bundle Hue's import routes take: one gzip OTLP/JSON file per
- * batch, one file per large value, and `manifest.json`, whose digest and totals
- * `prepare_trace_import` is called with. Nothing is sent anywhere.
+ * the format registry (`import-formats/registry.ts`) recognizes and writes the bundle Hue's
+ * import routes take: one gzip OTLP/JSON file per batch, one file per large value, and
+ * `manifest.json`, whose digest and totals `prepare_trace_import` is called with. Nothing is sent
+ * anywhere.
  */
 /** Bounds on what one preparation reads. */
 export declare const PREPARE_LIMITS: {
     /** One source file, or one archive member. */
     readonly fileBytes: number;
-    /** Every source file together. */
+    /** Every source file together, decompressed. Every trace is held until all are read, at about
+     * seven times its source size, so this keeps a run inside a 2 GiB JavaScript heap (Node.js's
+     * default on a machine with 8 GiB of memory). */
     readonly totalBytes: number;
     /** Files one directory tree or archive may hold. */
     readonly files: 50000;
@@ -23,18 +28,17 @@ export interface PrepareReport {
     totals: TraceImportTotals;
     source: TraceImportManifest["source"];
     output_directory: string;
-    /** Traces recognized per format. */
-    formats: Record<TraceImportFormat, number>;
+    /** Traces prepared per format id, for the formats that held any. */
+    formats: Record<string, number>;
     files: {
-        supported: {
-            file: string;
-            format: TraceImportFormat;
-            traces: number;
-        }[];
-        unsupported: {
-            file: string;
-            reason: string;
-        }[];
+        supported: ReadResult["supported"];
+        /** Files of which nothing could be read, and why. */
+        unsupported: ReadResult["unsupported"];
+        /** Records of a read file (a line of JSON Lines, a record of a JSON array) that were not. */
+        skipped: ReadResult["skipped"];
+        /** What was read with a repair (a damaged gzip or zstd file read up to the damage, `NaN` read
+         * as null) or read once though the input held it more than once. */
+        notes: ReadResult["notes"];
     };
     traces: {
         without_identity: number;
@@ -44,12 +48,10 @@ export interface PrepareReport {
             traces: number;
             spans: number;
         };
-        /** Traces and spans the sources held that could not be converted. */
-        refused: {
-            file?: string;
-            trace_id?: string;
-            reason: string;
-        }[];
+        /** Traces a documented rule supplied instants for, per rule (`hue.import.timing`). */
+        timing: Record<string, number>;
+        /** Traces and records the sources held that could not be converted. */
+        refused: ReadResult["refused"];
     };
     blobs: number;
 }
@@ -62,6 +64,8 @@ export declare function defaultOutputDirectory(input: string): string;
 export declare function manifestTooLarge(bytes: Uint8Array): string | undefined;
 export interface PrepareOptions {
     out?: string;
+    /** `--user-key` and `--session-key` (`import-formats/identity.ts`). */
+    keys?: IdentityKeys;
 }
 /** Prepares the bundle; resolves to the report, or throws a {@link PrepareError}. */
 export declare function prepareTraceBundle(input: string, options?: PrepareOptions): Promise<PrepareReport>;

package/dist/cli/traces-import-prepare.js

@@ -3,20 +3,25 @@ import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from "nod
 import { basename, join, relative, resolve, sep } from "node:path";
 import { gzipSync } from "node:zlib";
 import { sdkVersion } from "../version.js";
-import { batchEntries, ConversionError, convertAtifExport, detectFormat, LangfuseTraceCollector, manifestTotals, manifestTraceHasIdentity, OtlpTraceCollector, sha256Hex, traceImportFormats, traceImportLimits, validateManifest, } from "./traces-import-convert.js";
+import { ImportReader } from "./import-formats/reader.js";
+import { adapterById } from "./import-formats/registry.js";
+import { batchEntries, ConversionError, manifestTotals, manifestTraceHasIdentity, traceImportFormats, traceImportLimits, validateManifest, } from "./traces-import-convert.js";
 import { isZipSignature, ZipArchive, ZipError } from "./traces-import-zip.js";
 /**
  * `hue traces import prepare`: reads a file, a directory or a ZIP archive, converts every trace
- * it recognizes and writes the bundle Hue's import routes take: one gzip OTLP/JSON file per
- * batch, one file per large value, and `manifest.json`, whose digest and totals
- * `prepare_trace_import` is called with. Nothing is sent anywhere.
+ * the format registry (`import-formats/registry.ts`) recognizes and writes the bundle Hue's
+ * import routes take: one gzip OTLP/JSON file per batch, one file per large value, and
+ * `manifest.json`, whose digest and totals `prepare_trace_import` is called with. Nothing is sent
+ * anywhere.
  */
 /** Bounds on what one preparation reads. */
 export const PREPARE_LIMITS = {
     /** One source file, or one archive member. */
     fileBytes: 64 * 1024 * 1024,
-    /** Every source file together. */
-    totalBytes: 1024 * 1024 * 1024,
+    /** Every source file together, decompressed. Every trace is held until all are read, at about
+     * seven times its source size, so this keeps a run inside a 2 GiB JavaScript heap (Node.js's
+     * default on a machine with 8 GiB of memory). */
+    totalBytes: 256 * 1024 * 1024,
     /** Files one directory tree or archive may hold. */
     files: 50_000,
     /** How deep a directory tree is walked. */
@@ -211,117 +216,44 @@ async function writePrivate(path, bytes) {
     await writeFile(temporary, bytes, { mode: 0o600, flag: "w" });
     await rename(temporary, path);
 }
-/** Merges a converted trace into the collection: the same trace from two sources is one trace
- * when its entries agree, a conflict otherwise. */
-function merge(collected, conflicts, trace, sourceDigest) {
-    trace.sourceDigests.add(sourceDigest);
-    const held = collected.get(trace.traceId);
-    if (!held) {
-        collected.set(trace.traceId, trace);
-        return;
-    }
-    if (JSON.stringify(held.entries) !== JSON.stringify(trace.entries)) {
-        conflicts.set(trace.traceId, "the trace appears in two sources with different content");
-        return;
-    }
-    for (const digest of trace.sourceDigests)
-        held.sourceDigests.add(digest);
-}
 /** Prepares the bundle; resolves to the report, or throws a {@link PrepareError}. */
 export async function prepareTraceBundle(input, options = {}) {
     const outputDirectory = resolve(options.out ?? defaultOutputDirectory(input));
     const unsupported = [];
-    const supported = [];
-    const refused = [];
-    const otlp = new OtlpTraceCollector();
-    const langfuse = new LangfuseTraceCollector();
-    const whole = new Map();
-    const conflicts = new Map();
-    /** The file names each source digest was read under, so the traces an OTLP or Langfuse file
-     * held are counted once the traces are known: a trace may come from several files. */
-    const fileNames = new Map();
-    const tracesPerFile = new Map();
-    const nameFile = (digest, name) => {
-        const names = fileNames.get(digest) ?? new Set();
-        names.add(name);
-        fileNames.set(digest, names);
-    };
+    const reader = new ImportReader({
+        maxFileBytes: PREPARE_LIMITS.fileBytes,
+        unsupported,
+        ...(options.keys ? { keys: options.keys } : {}),
+    });
     let totalBytes = 0;
-    {
-        for await (const source of sourceFiles(input, unsupported)) {
-            totalBytes += source.size;
-            if (totalBytes > PREPARE_LIMITS.totalBytes)
-                throw new PrepareError(`The input holds more than ${PREPARE_LIMITS.totalBytes} bytes`);
-            let bytes;
-            try {
-                bytes = await source.read();
-            }
-            catch (error) {
-                unsupported.push({
-                    file: source.name,
-                    reason: error instanceof ZipError ? error.message : "the file could not be read",
-                });
-                continue;
-            }
-            const digest = sha256Hex(bytes);
-            const detected = detectFormat(bytes);
-            if (detected.format === "unsupported") {
-                unsupported.push({ file: source.name, reason: detected.reason });
-                continue;
-            }
-            const note = (problems) => {
-                for (const problem of problems)
-                    refused.push({
-                        file: source.name,
-                        ...(problem.traceId ? { trace_id: problem.traceId } : {}),
-                        reason: problem.reason,
-                    });
-            };
-            try {
-                if (detected.format === "otlp_json") {
-                    note(otlp.add(detected.envelopes, digest));
-                    nameFile(digest, source.name);
-                    supported.push({ file: source.name, format: "otlp_json", traces: 0 });
-                }
-                else if (detected.format === "langfuse_observations") {
-                    if (detected.unsafeIntegers)
-                        throw new ConversionError("Source JSON contains an unsafe number");
-                    langfuse.add(detected.observations, detected.envelope, digest);
-                    nameFile(digest, source.name);
-                    supported.push({ file: source.name, format: "langfuse_observations", traces: 0 });
-                }
-                else {
-                    const trace = convertAtifExport(detected, bytes.byteLength);
-                    merge(whole, conflicts, trace, digest);
-                    supported.push({ file: source.name, format: "atif", traces: 1 });
-                }
-            }
-            catch (error) {
-                if (!(error instanceof ConversionError))
-                    throw error;
-                unsupported.push({ file: source.name, reason: error.message });
-            }
+    const countBytes = (bytes) => {
+        totalBytes += bytes;
+        if (totalBytes > PREPARE_LIMITS.totalBytes)
+            throw new PrepareError(`The input holds more than ${PREPARE_LIMITS.totalBytes} bytes decompressed; prepare it in parts of at most that size, each to its own --out`);
+    };
+    for await (const source of sourceFiles(input, unsupported)) {
+        countBytes(source.size);
+        let bytes;
+        try {
+            bytes = await source.read();
         }
-    }
-    for (const collector of [otlp, langfuse]) {
-        const finished = collector.finish();
-        for (const problem of finished.refused)
-            refused.push({
-                ...(problem.traceId ? { trace_id: problem.traceId } : {}),
-                reason: problem.reason,
+        catch (error) {
+            unsupported.push({
+                file: source.name,
+                reason: error instanceof ZipError ? error.message : "the file could not be read",
             });
-        for (const trace of finished.traces) {
-            const first = [...trace.sourceDigests][0] ?? "";
-            merge(whole, conflicts, trace, first);
+            continue;
         }
+        // Decompressed content counts toward the bound too.
+        countBytes(Math.max(0, reader.read(source.name, bytes) - bytes.byteLength));
     }
-    for (const [traceId, reason] of conflicts) {
-        whole.delete(traceId);
-        refused.push({ trace_id: traceId, reason });
-    }
-    const traces = [...whole.values()].sort((a, b) => (a.traceId < b.traceId ? -1 : 1));
+    const read = reader.finish();
+    const refused = read.refused;
+    const traces = read.traces;
     if (!traces.length) {
-        const problems = [...unsupported, ...refused].slice(0, 3).map((item) => item.reason);
+        const problems = [...unsupported, ...read.skipped, ...refused]
+            .slice(0, 3)
+            .map((item) => item.reason);
         throw new PrepareError(`No trace was recognized in ${input}${problems.length ? ` (${problems.join("; ")})` : ""}`);
     }
     if (traces.length > traceImportLimits.traces)
@@ -329,11 +261,8 @@ export async function prepareTraceBundle(input, options = {}) {
     await prepareOutputDirectory(outputDirectory);
     const manifestTraces = [];
     const formats = new Set();
-    const formatCounts = {
-        otlp_json: 0,
-        langfuse_observations: 0,
-        atif: 0,
-    };
+    const formatCounts = {};
+    const timing = {};
     const byOrigin = {
         production: 0,
         evaluation: 0,
@@ -403,8 +332,14 @@ export async function prepareTraceBundle(input, options = {}) {
             ...(sourceDigest ? { source_digest: sourceDigest } : {}),
         };
         manifestTraces.push(declared);
-        formats.add(trace.format);
-        formatCounts[trace.format]++;
+        // What was written is let go: the run holds each trace's spans only until they are on disk.
+        trace.entries = [];
+        for (const blob of trace.blobs)
+            blob.bytes = new Uint8Array(0);
+        formats.add(adapterById(trace.format).manifestFormat);
+        formatCounts[trace.format] = (formatCounts[trace.format] ?? 0) + 1;
+        for (const rule of trace.inferredTiming ?? [])
+            timing[rule] = (timing[rule] ?? 0) + 1;
         byOrigin[trace.origin]++;
         if (!manifestTraceHasIdentity(declared))
             withoutIdentity++;
@@ -412,16 +347,9 @@ export async function prepareTraceBundle(input, options = {}) {
             remappedTraces++;
         remappedSpans += trace.remappedSpans;
         blobCount += trace.blobs.length;
-        if (trace.format !== "atif")
-            for (const digest of trace.sourceDigests)
-                for (const name of fileNames.get(digest) ?? [])
-                    tracesPerFile.set(name, (tracesPerFile.get(name) ?? 0) + 1);
     }
     if (!manifestTraces.length)
         throw new PrepareError(`No trace of ${input} could be prepared: ${refused[0]?.reason ?? ""}`);
-    for (const entry of supported)
-        if (entry.format !== "atif")
-            entry.traces = tracesPerFile.get(entry.file) ?? 0;
     const manifest = {
         version: 1,
         source: {
@@ -445,11 +373,12 @@ export async function prepareTraceBundle(input, options = {}) {
         source: manifest.source,
         output_directory: outputDirectory,
         formats: formatCounts,
-        files: { supported, unsupported },
+        files: { supported: read.supported, unsupported, skipped: read.skipped, notes: read.notes },
         traces: {
             without_identity: withoutIdentity,
             by_origin: byOrigin,
             remapped: { traces: remappedTraces, spans: remappedSpans },
+            timing,
             refused,
         },
         blobs: blobCount,

package/dist/cli/traces-import.d.ts

@@ -2,9 +2,9 @@ import { type UploadIo } from "./traces-import-upload.js";
 /**
  * `hue traces import`: imports a bundle of existing traces into Hue in two steps that keep the
  * payloads on this machine until the agent has authorized their delivery. `prepare` converts a
- * file, directory or ZIP archive of OTLP/JSON, Langfuse observation or ATIF exports into a
- * bundle and prints its manifest digest and totals; `prepare_trace_import` (Hue MCP) takes
- * those and answers an import authorization; `upload` delivers the bundle with it.
+ * file, directory or ZIP archive of trace exports (`import-formats/registry.ts`) into a bundle
+ * and prints its manifest digest and totals; `prepare_trace_import` (Hue MCP) takes those and
+ * answers an import authorization; `upload` delivers the bundle with it.
  */
 /** Streams and seams for {@link runTracesCommand}; tests inject these. */
 export interface TracesCommandIo extends UploadIo {
@@ -13,6 +13,6 @@ export interface TracesCommandIo extends UploadIo {
     env?: NodeJS.ProcessEnv;
     cwd?: string;
 }
-export declare const TRACES_USAGE = "Usage: hue traces import prepare <path> [--out <directory>] [--json]\n       hue traces import upload <directory> --authorization-file <file> [--import-url <url>] [--json]\n\nImport a bundle of existing traces into Hue. Nothing leaves this machine until the upload step,\nand no project key is involved: a Hue MCP connection authorizes the delivery.\n\nprepare  Reads a file, a directory or a ZIP archive and recognizes each file by its content:\n         OTLP/JSON trace exports ({\"resourceSpans\": [\u2026]}, also one per line), complete Langfuse\n         observation exports (the data or observations envelope) and text ATIF v1.7/v1.8 exports.\n         Every trace becomes gzip OTLP/JSON batches written to --out (default <path>.hue-import)\n         with manifest.json. The report names the manifest_digest and totals that\n         prepare_trace_import takes, the files it could not read, invalid vendor ids it mapped\n         to OpenTelemetry ids, traces without a history owner and the origin each source\n         recorded.\n  --out <directory>   Where the bundle is written (created with mode 0700)\n  --json              Print the report as one JSON object\n\nupload   Registers the manifest, then sends each trace's values and batches in order, two\n         requests at a time, checks every span's receipt, reconciles and completes. Progress is\n         kept in <directory>/progress.json, so running the same command again resumes.\n  --authorization-file <file>  A private file holding what prepare_trace_import answered: its\n                               JSON (authorization and upload_url), or the authorization\n                               (hue_it_\u2026) alone on the first line, the upload_url on the second.\n                               The authorization is never taken from the command line or the\n                               environment, and never printed.\n  --import-url <url>  The upload_url prepare_trace_import returned (https://\u2026/api/v1/trace-imports/<id>),\n                      when the authorization file does not hold it\n  --origin <url>      Accept only an import URL on this Hue origin\n  --json              Print one JSON progress object per line on stderr and the report on stdout\n\nExit codes: 0 prepared or completed, 1 not completed (the report says what to do next),\n2 usage error, 130 stopped (run the same command again to resume).";
+export declare const TRACES_USAGE: string;
 /** Runs `hue traces import …`; resolves to the exit code. */
 export declare function runTracesCommand(argv: string[], io?: TracesCommandIo): Promise<number>;

package/dist/cli/traces-import.js

@@ -1,25 +1,48 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { parseKeyPath } from "./import-formats/identity.js";
+import { importAdapters } from "./import-formats/registry.js";
 import { parseHueOrigin } from "./login.js";
 import { PrepareError, prepareTraceBundle } from "./traces-import-prepare.js";
 import { parseAuthorizationFile, parseImportUrl, UploadStop, uploadTraceBundle, } from "./traces-import-upload.js";
-export const TRACES_USAGE = `Usage: hue traces import prepare <path> [--out <directory>] [--json]
+/** The format ids, wrapped to the usage text's width under its indent. */
+function formatList(indent, width = 98) {
+    const lines = [];
+    let line = "";
+    for (const id of importAdapters.map((adapter) => adapter.id)) {
+        const next = line ? `${line}, ${id}` : id;
+        if (line && indent.length + next.length + 1 > width) {
+            lines.push(`${line},`);
+            line = id;
+        }
+        else
+            line = next;
+    }
+    lines.push(line);
+    return lines.map((text) => indent + text).join("\n");
+}
+export const TRACES_USAGE = `Usage: hue traces import prepare <path> [--out <directory>] [--user-key <key>] [--session-key <key>] [--json]
        hue traces import upload <directory> --authorization-file <file> [--import-url <url>] [--json]
 
 Import a bundle of existing traces into Hue. Nothing leaves this machine until the upload step,
 and no project key is involved: a Hue MCP connection authorizes the delivery.
 
-prepare  Reads a file, a directory or a ZIP archive and recognizes each file by its content:
-         OTLP/JSON trace exports ({"resourceSpans": […]}, also one per line), complete Langfuse
-         observation exports (the data or observations envelope) and text ATIF v1.7/v1.8 exports.
+prepare  Reads a file, a directory or a ZIP archive and recognizes each file by its content,
+         never its name: one JSON document, a JSON array of records, JSON Lines or binary OTLP,
+         gzip or zstd compressed or not, in these formats:
+${formatList("           ")}
          Every trace becomes gzip OTLP/JSON batches written to --out (default <path>.hue-import)
          with manifest.json. The report names the manifest_digest and totals that
-         prepare_trace_import takes, the files it could not read, invalid vendor ids it mapped
-         to OpenTelemetry ids, traces without a history owner and the origin each source
-         recorded.
-  --out <directory>   Where the bundle is written (created with mode 0700)
-  --json              Print the report as one JSON object
+         prepare_trace_import takes, the files, lines and records it could not read, invalid
+         vendor ids it mapped to OpenTelemetry ids, traces without a declared history owner and
+         the origin each source recorded.
+  --out <directory>    Where the bundle is written (created with mode 0700)
+  --user-key <key>     Where the export records each trace's end user under a key of its own: an
+                       attribute or metadata key (app.customer_id), or a JSON path into each
+                       source record ($.metadata.customer.id or /metadata/customer/id)
+  --session-key <key>  Where the export records each trace's conversation, the same way
+  --json               Print the report as one JSON object
 
 upload   Registers the manifest, then sends each trace's values and batches in order, two
          requests at a time, checks every span's receipt, reconciles and completes. Progress is
@@ -81,6 +104,8 @@ function parsePrepareArguments(argv) {
             strict: true,
             options: {
                 out: { type: "string" },
+                "user-key": { type: "string" },
+                "session-key": { type: "string" },
                 json: { type: "boolean", default: false },
             },
         });
@@ -96,10 +121,24 @@ async function prepare(argv, cwd, out, warn) {
             ? `Unexpected argument: ${positionals[1]}`
             : "Name the file, directory or archive to prepare");
     const input = resolve(cwd, positionals[0]);
+    const keys = {};
+    for (const [flag, kind] of [
+        ["user-key", "user"],
+        ["session-key", "session"],
+    ]) {
+        const text = values[flag];
+        if (text === undefined)
+            continue;
+        const path = parseKeyPath(text);
+        if (!path)
+            throw new UsageError(`--${flag} must be an attribute or metadata key, or a JSON path such as $.metadata.user_id or /metadata/user_id`);
+        keys[kind] = path;
+    }
     let report;
     try {
         report = await prepareTraceBundle(input, {
             ...(values.out !== undefined ? { out: resolve(cwd, values.out) } : {}),
+            ...(keys.user || keys.session ? { keys } : {}),
         });
     }
     catch (error) {
@@ -126,15 +165,28 @@ async function prepare(argv, cwd, out, warn) {
     out(`Totals: ${JSON.stringify(report.totals)}`);
     out(`Source: ${JSON.stringify(report.source)}`);
     if (report.traces.without_identity)
-        out(`${plural(report.traces.without_identity, "trace names", "traces name")} no history owner.`);
+        out(`${plural(report.traces.without_identity, "trace declares", "traces declare")} no history owner.`);
     const origins = Object.entries(report.traces.by_origin).filter(([, count]) => count);
     out(`Origin: ${origins.map(([origin, count]) => `${origin} ${count}`).join(", ")}.`);
     if (report.traces.remapped.traces)
         out(`Mapped invalid vendor ids to OpenTelemetry ids in ${plural(report.traces.remapped.traces, "trace")} (${plural(report.traces.remapped.spans, "span")}).`);
+    for (const [rule, count] of Object.entries(report.traces.timing))
+        out(`Instants the source did not record (${rule}): ${plural(count, "trace")}.`);
+    const where = (item) => [
+        item.file,
+        item.line !== undefined ? `line ${item.line}` : undefined,
+        item.record !== undefined ? `record ${item.record}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(" ");
     for (const file of report.files.unsupported)
         warn(`Not read: ${file.file}: ${file.reason}.`);
+    for (const record of report.files.skipped)
+        warn(`Not read: ${where(record)}: ${record.reason}.`);
+    for (const note of report.files.notes)
+        warn(`Note: ${where(note)}: ${note.reason}.`);
     for (const refusal of report.traces.refused)
-        warn(`Not converted: ${[refusal.file, refusal.trace_id ? `trace ${refusal.trace_id}` : undefined].filter(Boolean).join(" ")}: ${refusal.reason}.`);
+        warn(`Not converted: ${[where(refusal), refusal.trace_id ? `trace ${refusal.trace_id}` : undefined].filter(Boolean).join(" ")}: ${refusal.reason}.`);
     out("Next: call prepare_trace_import with manifest_digest, totals and source, write the authorization to a private file and run hue traces import upload.");
     return 0;
 }

package/dist/transport.d.ts

@@ -53,6 +53,9 @@ export declare class HueTransport {
     private failed;
     private spans;
     private logs;
+    private deliveryCohort?;
+    private deliveries;
+    private deliveryUploads;
     private pendingBytes;
     private dropped;
     /** Records of each trace the SDK never sent (dropped from the queue, refused as invalid or
@@ -81,6 +84,8 @@ export declare class HueTransport {
     private placeholdersRejected;
     private placeholders;
     private placeholderSources;
+    private forcedSpanDrains;
+    private completedSpanDrains;
     private batchSpans?;
     private limits;
     /** The rate-limit holds in progress, each ended early by calling it. */
@@ -120,11 +125,16 @@ export declare class HueTransport {
      * skipped silently.
      */
     private enqueue;
+    /** Register in the caller's request before it can return; outside Vercel this is a no-op. */
+    private protectDelivery;
+    private holdDelivery;
+    private finishDelivery;
     private track;
     /** Placeholders are built lazily, so input set right after a span starts is included. */
     private announceLiveSpans;
     private stopLiveTimer;
     private stopLiveSpans;
+    private beginSpanDrain;
     /** Holds the staged attachments of a log record being admitted with the queued record, within
      * the held-value budget; those the budget refuses are counted as not uploaded. */
     private admitLogParts;
@@ -144,6 +154,8 @@ export declare class HueTransport {
     private protectMedia;
     private releaseMediaIdentity;
     private sweepMedia;
+    /** Keep an export's warning aggregation within each cohort's upload ownership. */
+    private collectDeliveryUploads;
     /** Bounded: a trace whose root never arrives (an abandoned run) gives way to newer ones. */
     private countDropped;
     /** Cumulative counters and current queue gauges. */