@hue-run/sdk 0.18.1 → 0.19.0

package/dist/attachment.js

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
-import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
 import { types as utilTypes } from "node:util";
+import { MAX_BLOB_BYTES } from "./blobs.js";
 import { MAX_FILE_DATA_BYTES } from "./config.js";
 import { inlineFileBytes, isMediaContentType, isMediaName } from "./inline-files.js";
 /** How deep in a value an attachment's part may sit and still be uploaded: Hue reads media parts
@@ -19,41 +22,137 @@ function stringBytes(text) {
         return undefined;
     return Buffer.from(text, "base64");
 }
-/** A file's bytes, read through one descriptor and never past the limit. */
-function fileBytes(path) {
-    const descriptor = openSync(path, "r");
+/** How much of a file given by path is read at once, to hash it or to upload it. */
+const FILE_SLICE = 1024 * 1024;
+/**
+ * A regular file given by path: its bytes when it is no larger than 25 MiB, and otherwise, up to
+ * Hue's 1 GB upload limit, its size and SHA-256 from one reading pass a slice at a time, never
+ * holding it whole. Undefined for a file over its limit and for anything that is no regular file
+ * (a named pipe, a device), which is opened without waiting and never read; throws for one that
+ * cannot be opened.
+ */
+export function readPath(path) {
+    // Resolved first: the file read now is the one read again when it is uploaded.
+    const absolute = resolve(path);
+    // Without waiting: a named pipe would block the application until something wrote to it.
+    const descriptor = openSync(absolute, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
     try {
-        if (fstatSync(descriptor).size > MAX_FILE_DATA_BYTES)
+        const info = fstatSync(descriptor);
+        if (!info.isFile())
+            return undefined;
+        if (info.size <= MAX_FILE_DATA_BYTES) {
+            const bytes = fileBytes(descriptor);
+            return bytes ? { bytes } : undefined;
+        }
+        if (info.size > MAX_BLOB_BYTES)
             return undefined;
-        // Read to its end, which may lie past its size as stated (a file that grew, a pipe), but
-        // never more than one byte past the limit.
-        const parts = [];
-        let total = 0;
+        const hash = createHash("sha256");
+        const slice = Buffer.allocUnsafe(FILE_SLICE);
+        let size = 0;
         for (;;) {
-            const room = Math.min(1 << 20, MAX_FILE_DATA_BYTES + 1 - total);
-            if (room <= 0)
-                return undefined;
-            const buffer = Buffer.alloc(room);
-            const read = readSync(descriptor, buffer, 0, room, null);
+            const read = readSync(descriptor, slice, 0, FILE_SLICE, null);
             if (read === 0)
                 break;
-            parts.push(buffer.subarray(0, read));
-            total += read;
+            size += read;
+            // A file that grew past the limit while it was read is refused, not read on.
+            if (size > MAX_BLOB_BYTES)
+                return undefined;
+            hash.update(slice.subarray(0, read));
         }
-        return Buffer.concat(parts, total);
+        return { file: { path: absolute, size, sha256: hash.digest("hex") } };
     }
     finally {
         closeSync(descriptor);
     }
 }
+/**
+ * A file given by path as an upload body, read from disk a slice at a time. Each slice is hashed as
+ * it is read and sent once the next one is read; the last is sent only once the file ended at its
+ * recorded size with its recorded SHA-256. A file that changed since it was recorded, or can no
+ * longer be read, ends the read with an error before its body is complete and sets `changed`, so
+ * the upload is abandoned and the value is counted as not uploaded; so does a path that is no
+ * longer a regular file, which is opened without waiting (a named pipe in its place would wait for
+ * a writer) and never read. Hue's presigned PUT also signs the size and SHA-256, so the store
+ * refuses a body that differs.
+ */
+export function fileSource(file) {
+    const source = {
+        size: file.size,
+        async *chunks() {
+            // Each read starts fresh: a retried upload reads the file again.
+            source.changed = false;
+            const changed = () => {
+                source.changed = true;
+                return new Error("The file changed after it was recorded");
+            };
+            const handle = await open(file.path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0)).catch(() => {
+                throw changed();
+            });
+            try {
+                const info = await handle.stat().catch(() => undefined);
+                if (!info?.isFile())
+                    throw changed();
+                const hash = createHash("sha256");
+                let size = 0;
+                let pending;
+                // Two buffers in turn: the slice withheld until the next is read, and the next. A reader
+                // is done with a slice before it asks for the next, so each buffer is free when reused.
+                const buffers = [Buffer.allocUnsafe(FILE_SLICE), Buffer.allocUnsafe(FILE_SLICE)];
+                for (let turn = 0;; turn ^= 1) {
+                    const slice = buffers[turn];
+                    const { bytesRead } = await handle.read(slice, 0, FILE_SLICE, null).catch(() => {
+                        throw changed();
+                    });
+                    if (bytesRead === 0)
+                        break;
+                    size += bytesRead;
+                    if (size > file.size)
+                        throw changed();
+                    const read = slice.subarray(0, bytesRead);
+                    hash.update(read);
+                    if (pending)
+                        yield pending;
+                    pending = read;
+                }
+                if (size !== file.size || hash.digest("hex") !== file.sha256)
+                    throw changed();
+                if (pending)
+                    yield pending;
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+        },
+    };
+    return source;
+}
+/** A file's bytes, read through one descriptor and never past the in-memory limit. */
+function fileBytes(descriptor) {
+    // Read to its end, which may lie past its size as stated (a file that grew), but never more
+    // than one byte past the limit.
+    const parts = [];
+    let total = 0;
+    for (;;) {
+        const room = Math.min(1 << 20, MAX_FILE_DATA_BYTES + 1 - total);
+        if (room <= 0)
+            return undefined;
+        const buffer = Buffer.alloc(room);
+        const read = readSync(descriptor, buffer, 0, room, null);
+        if (read === 0)
+            break;
+        parts.push(buffer.subarray(0, read));
+        total += read;
+    }
+    return Buffer.concat(parts, total);
+}
 function attachmentBytes(options) {
     const { data, path } = options;
     if ((data === undefined) === (path === undefined))
         return undefined;
+    if (path !== undefined)
+        return typeof path === "string" && path ? readPath(path) : undefined;
     let bytes;
-    if (typeof path === "string")
-        bytes = path ? fileBytes(path) : undefined;
-    else if (typeof data === "string") {
+    if (typeof data === "string") {
         if (data.length > 4 * MAX_FILE_DATA_BYTES)
             return undefined;
         bytes = stringBytes(data);
@@ -70,7 +169,7 @@ function attachmentBytes(options) {
             return undefined;
         bytes = new Uint8Array(data.slice(0));
     }
-    return bytes && bytes.byteLength <= MAX_FILE_DATA_BYTES ? bytes : undefined;
+    return bytes && bytes.byteLength <= MAX_FILE_DATA_BYTES ? { bytes } : undefined;
 }
 /**
  * A file placed in a recorded value, the equivalent of Langfuse's `LangfuseMedia` and
@@ -80,10 +179,16 @@ function attachmentBytes(options) {
  * names the file by digest (`{ type: "blob", mime_type, modality, sha256, size, name }`) and
  * uploads its bytes during export, listed under the record's `hue.blobs`.
  *
- * The bytes are read and hashed when the attachment is created; `data` and `path` are limited to
- * 25 MiB. Creating one never throws: an attachment without exactly one of `data` and `path`, with
- * unreadable data, larger data or an invalid `contentType` records `null` where it is placed and
- * counts an instrumentation failure; an invalid `name` alone is omitted and counted.
+ * The bytes are read and hashed when the attachment is created; `data` is limited to 25 MiB, as
+ * the bytes are held in memory until they are uploaded. A `path` names a regular file, opened
+ * without waiting: anything else, such as a named pipe, is invalid. One up to 25 MiB is read then
+ * too; a larger regular file, up to Hue's 1 GB upload limit, is hashed then a slice at a time and read
+ * again from disk when it is uploaded, so it must stay in place and unchanged until the client
+ * flushes: a file whose size or SHA-256 then differs is not uploaded and counts as an upload
+ * fallback, its part keeping the digest it was recorded with. Creating one never throws: an
+ * attachment without exactly one of `data` and `path`, with unreadable data, larger data or an
+ * invalid `contentType` records `null` where it is placed and counts an instrumentation failure;
+ * an invalid `name` alone is omitted and counted.
  */
 export class Attachment {
     /** The media type given. */
@@ -97,21 +202,24 @@ export class Attachment {
     constructor(options) {
         const contentType = options?.contentType;
         const name = options?.name;
-        let bytes;
+        let read;
         try {
-            bytes = isMediaContentType(contentType) ? attachmentBytes(options) : undefined;
+            read = isMediaContentType(contentType) ? attachmentBytes(options) : undefined;
         }
         catch {
             // An unreadable path, or data that is not bytes: the attachment is invalid.
-            bytes = undefined;
+            read = undefined;
         }
-        const sha256 = bytes ? createHash("sha256").update(bytes).digest("hex") : undefined;
+        const bytes = read && "bytes" in read ? read.bytes : undefined;
+        const file = read && "file" in read ? read.file : undefined;
+        const sha256 = bytes ? createHash("sha256").update(bytes).digest("hex") : file?.sha256;
         this.contentType = typeof contentType === "string" ? contentType : "";
         this.name = isMediaName(name) ? name : undefined;
         this.sha256 = sha256;
-        this.size = bytes?.byteLength;
+        this.size = bytes?.byteLength ?? file?.size;
         states.set(this, {
-            ...(bytes ? { bytes, sha256 } : {}),
+            ...(bytes ? { bytes, sha256, size: bytes.byteLength } : {}),
+            ...(file ? { file, sha256, size: file.size } : {}),
             contentType: this.contentType,
             ...(this.name === undefined ? {} : { name: this.name }),
             invalidName: name !== undefined && name !== null && this.name === undefined,
@@ -144,14 +252,14 @@ export function modalityOf(contentType) {
 /** An attachment's digest-form GenAI part, the name only with content capture; undefined for an
  * invalid attachment. */
 export function attachmentPart(state, captureContent) {
-    if (!state.bytes || !state.sha256)
+    if (state.size === undefined || !state.sha256)
         return undefined;
     return {
         type: "blob",
         mime_type: state.contentType,
         modality: modalityOf(state.contentType),
         sha256: state.sha256,
-        size: state.bytes.byteLength,
+        size: state.size,
         ...(captureContent && state.name !== undefined ? { name: state.name } : {}),
     };
 }

package/dist/blobs.d.ts

@@ -1,10 +1,13 @@
 import { type HrTime } from "@opentelemetry/api";
 import { type MediaDigestMemo, type FileDigest } from "./inline-files.js";
+import { type ByteSource } from "./large-media.js";
 /**
  * Large values and binary media travel apart from their span through reservation, presigned PUT,
- * and completion. Text keeps a 16 KiB prefix. Binary media keeps digest metadata on its part.
- * Successful uploads are listed in `hue.blobs`; failures keep inline fallback or file metadata,
- * are reported as warnings, and are counted.
+ * and completion. Export hashes each value, writes its reference (text keeps a 16 KiB prefix,
+ * binary media digest metadata on its part) and its `hue.blobs` entry, and sends the record; the
+ * upload runs afterwards in the background, as Langfuse uploads media. A value refused when its
+ * record is exported keeps its inline fallback or file metadata; an upload that fails after export
+ * leaves its entry, which Hue reads as missing. Both are reported as warnings and counted.
  */
 /** The span attribute listing the values the SDK uploaded apart from the span: one compact JSON
  * object per value, `{"key", "sha256", "size", "content_type"}`, with an optional `name`. */
@@ -16,18 +19,28 @@ export declare const BLOB_PREFIX_BYTES: number;
 /** The entries one record's `hue.blobs` may list; Hue reads no more. */
 export declare const MAX_BLOB_ENTRIES = 64;
 /**
- * The values over the inline limit that queued spans may hold whole for upload at once, charged
- * apart from `maxQueueBytes` (a string as two bytes a code unit, bytes as themselves). A value
- * the budget cannot hold is cut when it is queued, as before uploads existed; a single value
- * larger than the whole budget is held while nothing else is.
+ * The values over the inline limit that queued records and unsettled uploads may hold whole at
+ * once, charged apart from `maxQueueBytes` (a string as two bytes a code unit, bytes as
+ * themselves): each is held until its record is exported and its upload settles. A value the
+ * budget cannot hold is cut when it is queued, as before uploads existed; a single value larger
+ * than the whole budget is held while nothing else is.
  */
 export declare const MAX_HELD_BLOB_BYTES: number;
-/** How long one export may spend uploading its values, on top of its requests. */
+/** The longest wait before an upload's next attempt, a `Retry-After` included. */
+export declare const MAX_RETRY_AFTER_MILLIS = 60000;
+/** How long one export may spend hashing its values: past it a value keeps its fallback. Also
+ * the import's least upload deadline, and part of an upload's lifetime. */
 export declare function uploadBudgetMillis(timeoutMillis: number): number;
+/** How long one upload may take from when its record's export queued it: six export timeouts for
+ * its requests and up to a minute of Retry-After of its own. */
+export declare function uploadLifetimeMillis(timeoutMillis: number): number;
 /** Why content kept its fallback instead of being uploaded. */
 export type FallbackReason = "unsupported" | "failed" | "tooLarge" | "budget";
 /** The fixed description of each fallback, as an export issue reports it. */
 export declare const FALLBACK_MESSAGES: Record<FallbackReason, string>;
+/** The fixed description of each failure of an upload that ran after its record was exported:
+ * the record lists the value under `hue.blobs`, and Hue reads it as missing. */
+export declare const LATE_FALLBACK_MESSAGES: Record<FallbackReason, string>;
 /** A span's own attribute value the redaction left whole for the upload step to place. */
 export interface OffloadCandidate {
     key: string;
@@ -43,6 +56,9 @@ export interface OffloadCollector {
      * export inspects only these. Absent for a record admission did not copy, and for a log record,
      * which export inspects within its own allowance. */
     inspected?: ReadonlySet<string> | undefined;
+    /** The span's own attributes admission held whole for upload past the inspection bounds: export
+     * reads their media in place (`readLargeMediaText`). */
+    large?: ReadonlySet<string> | undefined;
     /** Set for a log record: its values over the inline limit are cut, never uploaded whole; only
      * the media in its inspected attributes and its body upload, with the attachments placed in
      * its body (`attachments`, keyed `body#<pointer>`). */
@@ -56,7 +72,8 @@ export interface OffloadCollector {
     bodyCut?: Set<string>;
 }
 export interface MediaAttachment {
-    bytes: Uint8Array;
+    /** The file's bytes, or for a file given by path over the in-memory limit, its source on disk. */
+    bytes: Uint8Array | ByteSource;
     digest: FileDigest;
     contentType: string;
     name?: string;
@@ -79,6 +96,21 @@ export interface OffloadTally {
 }
 export declare function newTally(): OffloadTally;
 export declare function countFallback(tally: OffloadTally, reason: FallbackReason, traceId: string): void;
+/** Adds one tally's outcomes to another's. */
+export declare function mergeTally(into: OffloadTally, from: OffloadTally): void;
+/** Adds `from` to `into` once `settled` all settle. Built apart from the step that queued the
+ * uploads, so a pending upload keeps alive the two tallies alone, never that step's record. */
+export declare function mergeWhenSettled(into: OffloadTally, from: OffloadTally, settled: Promise<void>[]): Promise<void>;
+/** The uploads an export queued after placing its records, and what they came to once settled:
+ * each record's own are added when its placement returns. */
+export interface LateUploads {
+    tally: OffloadTally;
+    settled: Promise<void>[];
+    /** Told of each upload as it is queued: when it settles, how many of the bytes it charges its
+     * record holds too (none for bytes decoded or rewritten apart from the record), and when that
+     * charge is released. */
+    queued?(settled: Promise<void>, shared: number, released: Promise<void>): void;
+}
 /** A media type accepted by the upload contract. */
 export declare function isBlobContentType(value: unknown): value is string;
 /** The media type an uploaded text is stored under: JSON when it reads as a JSON object or array
@@ -88,26 +120,35 @@ export declare function textContentType(text: string): string;
  * as its own copy so the whole value is not kept alive by it. */
 export declare function blobPrefix(value: string): string;
 export declare function blobPrefix(value: Uint8Array): Uint8Array;
+/** A value's size in bytes as it is uploaded: a string's UTF-8 encoding, counted, not made. */
+export declare function sizeOf(value: string | Uint8Array | ByteSource): number;
+/** The bytes a value holds in memory: none for a source read as it is uploaded. */
+export declare function heldBytesOf(value: Uint8Array | ByteSource): number;
 /** The SHA-256 (lowercase hex) and byte size of what an upload of `value` carries, yielding to
- * the event loop between slices so a large value does not stall the application. */
-export declare function digestOf(value: string | Uint8Array): Promise<{
+ * the event loop between slices so a large value does not stall the application. Past
+ * `deadline`, it throws rather than read on. */
+export declare function digestOf(value: string | Uint8Array | ByteSource, deadline?: number): Promise<{
     sha256: string;
     size: number;
 }>;
 /** The `hue.blobs` element for one uploaded value. */
 export declare function blobEntry(key: string, sha256: string, size: number, contentType: string, name?: string): string;
-/** What one export's uploads share: their deadline, and the export's hold for a receiver that
- * limited the rate (`wait` resolves false when the hold may not take `millis` more). */
+/** What an upload may spend: its deadline, and its wait before another attempt (`wait` resolves
+ * false when the wait was ended early or may not be taken). An export's own context bounds its
+ * hashing only. */
 export interface UploadContext {
     deadline: number;
     wait(millis: number): Promise<boolean>;
 }
+/** An upload's outcome; `changed` when the value's own source no longer held its bytes (a file
+ * that changed since it was recorded), which says nothing of another reference's bytes. */
 type Outcome = {
     ok: true;
     contentType: string;
 } | {
     ok: false;
     reason: FallbackReason;
+    changed?: boolean;
 };
 /** The upload route's options, from the transport's validated options. */
 export interface UploaderOptions {
@@ -119,50 +160,98 @@ export interface UploaderOptions {
 }
 /**
  * Uploads values to Hue: reserves each with `POST /api/v1/otlp/blobs`, PUTs its bytes to the
- * presigned URL Hue answers (skipped when Hue already stores the value), and completes it. At
- * most {@link UPLOAD_CONCURRENCY} uploads run at once; every request has a deadline and none
- * follows a redirect. A receiver without the route (a 404 without Hue's JSON error, a 405 or
- * 501, or a 200 that is no reservation) is remembered for {@link UNSUPPORTED_PAUSE_MILLIS}, and a
- * transient failure or a refusal that is not about the value alone pauses uploads for
- * {@link FAILURE_PAUSE_MILLIS}, so values fall back to the inline cut instead of retrying.
+ * presigned URL Hue answers (skipped when Hue already stores the value), and completes it. An
+ * export queues its values ({@link enqueue}) and sends its records without waiting for them; the
+ * import stores each value before it sends its span ({@link store}). At most
+ * {@link UPLOAD_CONCURRENCY} uploads run at once, and {@link HASH_CONCURRENCY} hashes apart from
+ * them. A reservation or PUT that gets no answer, a 408, a 429 or a 5xx is tried
+ * {@link UPLOAD_ATTEMPTS} times; every request has a deadline and none follows a redirect. A
+ * receiver without the route (a 404 without Hue's JSON error, a 405 or 501, or a 200 that is no
+ * reservation) is remembered for {@link UNSUPPORTED_PAUSE_MILLIS}: values exported meanwhile keep
+ * their fallback, never an entry the receiver cannot resolve.
  */
 export declare class BlobUploader {
     private readonly options;
+    /** Until when the receiver is taken to lack the upload route. */
     private unsupportedUntil;
-    private pausedUntil;
     private closed;
-    private running;
-    private waiting;
+    private uploads;
+    private hashes;
+    private queued;
+    private queuedBytes;
+    /** What queued uploads keep alive, each charged once, from the first upload holding it until
+     * the last settles: two files read in place from one recorded string charge it once, whole. */
+    private holding;
+    private sleeps;
     private requests;
     private outcomes;
+    /** The first wait before another attempt, doubled each time; tests shorten it. */
+    private retryDelayMillis;
+    /** How long a queued upload may take; tests shorten it. */
+    private lifetimeMillis;
     constructor(options: UploaderOptions);
     /** Whether a value over the inline limit is worth holding whole for upload now. */
     available(): boolean;
     /** Whether the receiver lacks the upload route, as it last answered. */
     unsupported(): boolean;
-    /** Ends uploads in flight and refuses new ones: their values fall back to the inline cut. */
+    /** Ends uploads in flight, queued uploads and their waits, and refuses new ones: values not
+     * yet exported fall back to the inline cut, and uploads queued by exported records fail. */
     close(): void;
     /** Runs `work` once fewer than {@link UPLOAD_CONCURRENCY} uploads are in flight. */
     limit<R>(work: () => Promise<R>): Promise<R>;
+    /** The SHA-256 and size of `value` (see {@link digestOf}), hashed in a place of its own: an
+     * export never waits for an upload to hash its values. */
+    digest(value: string | Uint8Array | ByteSource, deadline: number): Promise<FileDigest>;
+    /** The bytes queued uploads keep alive until they settle. */
+    pendingBytes(): number;
     /** Why a value cannot be uploaded right now without trying, if it cannot. */
     refusal(): FallbackReason | undefined;
-    private pause;
+    /** Why the value cannot be uploaded at all, whatever Hue would answer. */
+    private invalid;
+    /**
+     * Queues `value`'s upload for an exported record, deciding now what the record lists: a value
+     * refused without trying (see {@link refusal}), invalid, or past the queue's
+     * {@link MAX_QUEUED_UPLOADS} uploads or {@link MAX_HELD_BLOB_BYTES} keeps its fallback. A queued
+     * upload runs within {@link uploadLifetimeMillis} of now, holding `value` until it settles;
+     * `done` never rejects. `bytes` is what it adds to {@link pendingBytes}: the strings it keeps
+     * alive that no other queued upload holds, charged until `released`, once the last upload
+     * holding them settles.
+     */
+    enqueue(traceId: string, key: string, value: string | Uint8Array | ByteSource, contentType: string, digest: FileDigest): {
+        ok: false;
+        reason: FallbackReason;
+    } | {
+        ok: true;
+        done: Promise<Outcome>;
+        bytes: number;
+        released: Promise<void>;
+    };
+    /** Waits `millis`; false when {@link close} ended the wait first. The timer keeps the process
+     * running, as an export in progress does, within the upload's lifetime. */
+    sleep(millis: number): Promise<boolean>;
+    /** Waits before attempt `attempt + 1`: `Retry-After` when the answer gave one, otherwise a
+     * second doubled each attempt with jitter, at most a minute. The upload's place is given up
+     * meanwhile, so uploads queued behind it run. False when the wait would pass the upload's
+     * deadline, was ended, or no place came free again before the deadline. */
+    private retryWait;
     /**
      * Stores `value` under `key` of the trace: reserved, uploaded unless Hue already holds it, and
      * completed. Only a fresh upload takes a {@link limit} slot: another reference to bytes the
      * trace is already storing shares that upload's outcome without one, so repeated files never
-     * hold the slots new files need. The caller must not hold a slot.
+     * hold the slots new files need. The caller must not hold a slot. Never rejects.
      */
-    store(traceId: string, key: string, value: string | Uint8Array, contentType: string, digest: FileDigest, upload: UploadContext): Promise<Outcome>;
+    store(traceId: string, key: string, value: string | Uint8Array | ByteSource, contentType: string, digest: FileDigest, upload: UploadContext): Promise<Outcome>;
     private storeFresh;
     private jsonHeaders;
-    /** Reserves the value: Hue answers that it holds it already, or a presigned PUT. A rate limit
-     * is waited out within the export's hold, a transient refusal retried once. */
+    /** Reserves the value: Hue answers that it holds it already, or a presigned PUT. No answer, a
+     * 408, a 429 or a 5xx other than 501 is tried again, after its `Retry-After` when it gave one,
+     * within the upload's deadline. */
     private reserve;
-    private delay;
     /** A 200 answer read: `exists`, or an upload whose URL and headers are usable as given. */
     private reservation;
-    /** The PUT of the value's bytes, with exactly the headers Hue signed. */
+    /** The PUT of the value's bytes, with exactly the headers Hue signed. A source that no longer
+     * holds its bytes (a file changed since it was recorded) ends the request before its body is
+     * complete, and fails the value without a retry. */
     private put;
     /**
      * One HTTP request with a deadline and an idle timeout, never following a redirect, its
@@ -172,32 +261,39 @@ export declare class BlobUploader {
      */
     private request;
 }
-/** Where one export's values are uploaded, and what it learned of them. */
+/** Where one record's values are uploaded, and what it learned of them. */
 export interface OffloadOptions {
     uploader: BlobUploader;
     traceId: string;
     /** The receiver's inline value limit. */
     valueBytes: number;
+    /** The deadline for hashing, and for a blocking store (no `background`) its uploads too. */
     upload: UploadContext;
     tally: OffloadTally;
     memo?: MediaDigestMemo;
+    /** For tests: the length past which a long string is read in place (`LONG_STRING_UNITS`). */
+    longUnits?: number;
+    /** Set by an export: values are placed as uploaded and their uploads queued, each counted in
+     * `background.tally` once it settles; `tally` counts the values refused when placed. Absent
+     * for the import, which stores each value, under the type Hue stores it as, before placing it. */
+    background?: LateUploads;
 }
 /**
  * A span's own attributes with each candidate placed: binary media becomes a digest, while
- * text media over 64 KiB retains a 16 KiB prefix after upload or a digest on failure.
- * A value still over the inline limit is uploaded and replaced by its first
- * 16 KiB (or cut to the limit), each upload listed under `hue.blobs`, each whole value cut or
+ * text media over 64 KiB retains a 16 KiB prefix once uploaded or queued, or a digest when
+ * refused. A value still over the inline limit is uploaded and replaced by its first 16 KiB (or
+ * cut to the limit when refused), each upload listed under `hue.blobs`, each whole value cut or
  * uploaded listed under `hue.truncated`. Every fallback is counted in the tally.
  */
 export declare function offloadAttributes(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<Record<string, unknown>>;
 /**
  * A record's own attributes, and a log record's body, with each candidate placed (see
- * {@link offloadAttributes}). A file is uploaded and placed in its digest form (a text file in a
- * provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed `<attribute>#<pointer>` or, in
- * a log record's body, `body#<pointer>`. A file that is not uploaded keeps its bytes inline, except
- * in a span's own recorded messages, where it keeps its digest as before. A log record's values
- * over the inline limit are cut, never uploaded whole, and a body still over it is replaced by the
- * receiver's marker, as before.
+ * {@link offloadAttributes}). A file is uploaded (or, for an export, queued) and placed in its
+ * digest form (a text file in a provider part keeps a 16 KiB prefix), its `hue.blobs` entry keyed
+ * `<attribute>#<pointer>` or, in a log record's body, `body#<pointer>`. A file refused or not
+ * uploaded before it is placed keeps its bytes inline, except in a span's own recorded messages,
+ * where it keeps its digest as before. A log record's values over the inline limit are cut, never
+ * uploaded whole, and a body still over it is replaced by the receiver's marker, as before.
  */
 export declare function offloadRecord(attributes: Record<string, unknown>, collector: OffloadCollector, options: OffloadOptions): Promise<{
     attributes: Record<string, unknown>;