@hue-run/sdk 0.18.1 → 0.18.2

package/CLI.md

@@ -42,7 +42,7 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.18.1`, `@opentelemetry/api@1.9.1` and
+not a completed integration. TypeScript uses `@hue-run/sdk@0.18.2`, `@opentelemetry/api@1.9.1` and
 `@opentelemetry/context-async-hooks@2.11.0`; Python setup uses its separately tested package pin.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
@@ -379,8 +379,8 @@ and Hue never receives or stores them. The command is part of the `hue` executab
 #   LANGFUSE_PUBLIC_KEY=pk-lf-...
 #   LANGFUSE_SECRET_KEY=sk-lf-...
 #   LANGFUSE_BASE_URL=https://cloud.langfuse.com
-npx -y @hue-run/sdk@0.18.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.18.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.18.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.18.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` come from the environment or `--env-path`
@@ -591,7 +591,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.18.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.18.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -602,7 +602,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.18.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.18.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json
@@ -644,10 +644,10 @@ otherwise. Never hand the agent Hue-native tools (`context.tools`, `context.mcp`
 production agent lacks. Pin the SDK, so the agent's repository gains no dependency:
 
 ```sh
-npx -y @hue-run/sdk@0.18.1 eval --case "Refund an eligible charge" --command "node agent.js"
-npx -y @hue-run/sdk@0.18.1 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
-npx -y @hue-run/sdk@0.18.1 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
-npx -y @hue-run/sdk@0.18.1 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
+npx -y @hue-run/sdk@0.18.2 eval --case "Refund an eligible charge" --command "node agent.js"
+npx -y @hue-run/sdk@0.18.2 eval --case https://app.hue.run/projects/demo/scenarios/<id> --command "python agent.py" --timeout 120 --baseline <run id>
+npx -y @hue-run/sdk@0.18.2 eval --set "Billing regressions" --scorer-version <id> --command "node agent.js" --save-version
+npx -y @hue-run/sdk@0.18.2 eval --worker --command "node agent.js" --agent-key support-agent --revision <new-agent-revision>
 ```
 
 One invocation creates one run holding every selected case; it prints the run URL
@@ -685,7 +685,7 @@ export default function runMyAgent(inputs: JsonValue, context: SimulationTargetC
 ```
 
 ```sh
-npx -y @hue-run/sdk@0.18.1 eval --case "Refund an eligible charge" ./hue-agent.ts --content
+npx -y @hue-run/sdk@0.18.2 eval --case "Refund an eligible charge" ./hue-agent.ts --content
 ```
 
 `--scenario` remains an alias for `--case` for existing scripts. Pass one selection flag.

package/README.md

@@ -312,13 +312,23 @@ listed under `hue.truncated`. While uploads are available, `recordMessages` reco
 the value limit when it fits the limit with its files as their digest.
 
 Inspection is bounded to 8 Mi UTF-16 code units of text per attribute and 16 Mi per record, a log
-body's file contents included; a longer value uses the ordinary value limit. Inspection parses the
-value and decodes each file while the record is queued and again when it is exported, holding
-several copies of the value at once; larger files belong in an `Attachment` or in
-`hue.recordFile` with `upload` set, whose bytes are not parsed out of text. Resources, links and
-span events never upload inline media: in their recorded messages, media up to 64 KiB stays
-verbatim and larger media is replaced by its digest, as in 0.16, and log records that cannot
-upload (not correlated with a span, or while uploads are unavailable) keep the same rule. With
+body's file contents included. Within those bounds, inspection parses the value and decodes each
+file while the record is queued and again when it is exported. A span's own attribute past either
+bound that is held whole for upload (it is over the value limit) has its media read in place when
+it is exported, as a voice agent's audio usually needs: each string in it longer than 16 Ki code
+units and written without escapes as strict base64 or a base64 `data:` URL is decoded, hashed and
+uploaded a 1 MiB window at a time from the recorded text, never parsed or copied out of it, and a
+file may be up to Hue's 1 GB upload limit. The scan that finds those strings also reads the value
+a window at a time, between turns of the event loop, so no step of it stalls the application for
+long; a percent-escaped `data:` URL is parsed with the JSON around it. The value is placed exactly as one within the bounds: the same
+digest form, entries and fallbacks. The JSON around those strings, a file written with escapes or
+inside a JSON-encoded string included, is parsed within the 8 Mi bound; a value past it uses the
+ordinary value limit (it uploads whole). Each such value is read within that bound on its own, apart
+from the record's 16 Mi allowance, while it stays held within the 128 MiB for values awaiting
+upload. Log records keep the bounds. Resources, links and span
+events never upload inline media: in their recorded messages, media up to 64 KiB stays verbatim
+and larger media is replaced by its digest, as in 0.16, and log records that cannot upload (not
+correlated with a span, or while uploads are unavailable) keep the same rule. With
 `captureContent: false`, nothing is inspected or uploaded.
 
 ### Attach a file anywhere
@@ -345,10 +355,19 @@ await hue.withSpan(
 ```
 
 Give exactly one of `data` (a `Buffer`, typed array, `ArrayBuffer`, or a base64 string or `data:`
-URL) and `path` (read from the file system when the attachment is created), a `contentType` and
-optionally a `name`. The bytes are read and hashed when the attachment is created and are limited
-to 25 MiB, the `recordFile` limit: they are held in memory from then until export, within the
-128 MiB budget that queued spans share for values awaiting upload.
+URL) and `path` (a file on the file system), a `contentType` and optionally a `name`. `data` is
+read and hashed when the attachment is created and is limited to 25 MiB, the `recordFile` limit:
+it is held in memory from then until export, within the 128 MiB budget that queued spans share for
+values awaiting upload. A `path` names a regular file: anything else, such as a named pipe, is
+refused without waiting on it. A `path` up to 25 MiB is read the same way. A larger regular file, up to
+Hue's 1 GB upload limit, is not held: it is hashed a 1 MiB slice at a time when the attachment is
+created and read again from disk when it is uploaded, each slice hashed as it is sent and the last
+sent only once the file ended at the size and SHA-256 it was recorded with. Keep such a file in
+place and unchanged until the client flushes: one that changed, is gone or is no longer a regular
+file is not uploaded (the
+request ends before its body is complete, and Hue's upload URL signs the size and SHA-256, so the
+store refuses other bytes), and it counts in `report.uploadFallbacks`, its part keeping the digest
+it was recorded with.
 
 At its position the attachment is recorded as a GenAI `blob` part that names the file by digest,
 `{"type":"blob","mime_type":"application/pdf","modality":"document","sha256":"<64 hex>","size":48213,"name":"contract.pdf"}`,
@@ -392,9 +411,14 @@ await hue.withSpan("review contract", async () => {
 ```
 
 `upload` defaults to `false`, which hashes and measures `data` locally without exporting bytes.
-`data` is limited to 25 MiB. Larger data is omitted and counted as an instrumentation failure;
-pass `sha256` and `byteSize` when you already have them. Upload requires supplied bytes, content
-capture and an ordinary project key. It runs during export and adds a `hue.blobs` entry to the
+`data` is limited to 25 MiB, as it is held in memory until it is uploaded. Larger data is omitted
+and counted as an instrumentation failure; pass `sha256` and `byteSize` when you already have them.
+Give `path` instead of `data` for a file on disk: up to 25 MiB it is read as `data` is, and a larger
+regular file, up to Hue's 1 GB upload limit, is hashed a slice at a time now and, with `upload`,
+read again from disk when it is uploaded, as an [`Attachment`](#attach-a-file-anywhere) given by
+path is: it uploads only if it still has the size and SHA-256 it was recorded with. A file over
+1 GB, a path that is no regular file, or `data` and `path` together, is omitted and counted. Upload requires supplied bytes or a
+path, content capture and an ordinary project key. It runs during export and adds a `hue.blobs` entry to the
 same span, keyed `event:hue.file:<sha256>`, while preserving the event. An export fits every
 span's events and entries before it uploads any of these files, then uploads the files of all its
 spans together, four at a time; a file whose event was redacted or shed is not uploaded.
@@ -497,8 +521,8 @@ the Langfuse project's own keys (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, a
 `HUE_API_KEY`:
 
 ```sh
-npx -y @hue-run/sdk@0.18.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
-npx -y @hue-run/sdk@0.18.1 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
+npx -y @hue-run/sdk@0.18.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --dry-run
+npx -y @hue-run/sdk@0.18.2 import langfuse --env-path .env.langfuse --from 2026-01-01 --media
 ```
 
 - It reads Langfuse Cloud and self-hosted v4 through the Observations API v2, and self-hosted v3
@@ -824,7 +848,9 @@ apart from their record, up to Hue's upload limit of 1,000,000,000 bytes:
 
 Hue stores the value under the trace, so the trace's retention, deletion and erasure cover it.
 Uploads run in the export, never on the application's thread: at most four at a time, each request
-within the export timeout, and all of one export's uploads within six export timeouts; a
+within the export timeout, and all of one export's uploads within six export timeouts (60 seconds
+at the default `timeoutMillis` of 10000), so a 1 GB file needs about 17 MB/s at the defaults;
+raise `timeoutMillis` (up to 60000) for slower links. A
 transient failure is retried once. A rate-limited reservation (429) waits out its `Retry-After`
 within the export's 60-second hold. `flush()` and `shutdown()` wait for uploads like any export
 work, and a `shutdownSafe()` whose budget runs out ends the uploads in flight.
@@ -833,7 +859,8 @@ A value that cannot be uploaded (Hue or the store refused it or failed, the netw
 did, the receiver has no upload route, or the value is over 1 GB) is exported as before uploads
 existed: whole attributes keep a prefix up to the limit and are listed under `hue.truncated`;
 media parts keep their digest without a blob entry; failed opt-in `recordFile` uploads preserve
-the file event. The explicit helper limit is 25 MiB; whole attributes retain their 1 GB limit. Each
+the file event. Bytes given in memory to `recordFile` or an `Attachment` are limited to 25 MiB; a
+file given by path, a file read in place from a value and a whole attribute to 1 GB. Each
 export reports such values in a `warning` issue per cause, whose `count` is the values and
 `traceIds` their traces, and counts them in `report.uploadFallbacks`; successful uploads are counted
 in `report.uploadedValues`. Both counters include whole attributes, eligible media, attachments

package/dist/attachment.d.ts

@@ -1,12 +1,15 @@
+import type { ByteSource } from "./large-media.js";
 /** How deep in a value an attachment's part may sit and still be uploaded: Hue reads media parts
  * within ten levels of the value's root. */
 export declare const MAX_ATTACHMENT_DEPTH = 10;
 /** Options for {@link Attachment}. Give exactly one of `data` and `path`. */
 export interface AttachmentOptions {
     /** The file's bytes (a `Buffer`, typed array or `ArrayBuffer`), or a string holding them as
-     * base64 or a `data:` URL. */
+     * base64 or a `data:` URL; up to 25 MiB. */
     data?: ArrayBufferView | ArrayBuffer | string;
-    /** A file to read when the attachment is created (Node.js file system). */
+    /** A file to read (Node.js file system): up to 25 MiB it is read when the attachment is created;
+     * a larger regular file, up to Hue's 1 GB upload limit, is hashed then and read again from disk
+     * when it is uploaded. */
     path?: string;
     /** The file's media type, such as `image/png` or `application/pdf`. */
     contentType: string;
@@ -15,15 +18,50 @@ export interface AttachmentOptions {
 }
 /** What an attachment holds, read by the client and transport only. */
 export interface AttachmentState {
-    /** The file's bytes; undefined for an attachment that could not be read or is invalid. */
+    /** The file's bytes; undefined for a file read from disk when it is uploaded, and for an
+     * attachment that could not be read or is invalid. */
     bytes?: Uint8Array;
+    /** A file given by path over 25 MiB, read again from disk when it is uploaded. */
+    file?: PathFile;
     sha256?: string;
+    /** The file's size; undefined for an invalid attachment. */
+    size?: number;
     contentType: string;
     /** The name, when it is a valid media name. */
     name?: string;
     /** A name was given and is not a valid media name: it is omitted and counted. */
     invalidName: boolean;
 }
+/** A regular file given by path over the in-memory limit, as it was hashed when it was recorded:
+ * its absolute path, size and SHA-256. Its bytes are read again from disk when it is uploaded. */
+export interface PathFile {
+    path: string;
+    size: number;
+    sha256: string;
+}
+/**
+ * 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 declare function readPath(path: string): {
+    bytes: Uint8Array;
+} | {
+    file: PathFile;
+} | undefined;
+/**
+ * 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 declare function fileSource(file: PathFile): ByteSource;
 /**
  * A file placed in a recorded value, the equivalent of Langfuse's `LangfuseMedia` and
  * Braintrust's `Attachment`. Put it anywhere in a `withSpan()` input or output, in `model()`
@@ -32,10 +70,16 @@ export interface AttachmentState {
  * 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 declare class Attachment {
     /** The media type given. */

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,5 +1,6 @@
 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.
@@ -43,6 +44,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 +60,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;
@@ -88,9 +93,14 @@ 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;
 }>;
@@ -102,12 +112,15 @@ 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 {
@@ -153,7 +166,7 @@ export declare class BlobUploader {
      * 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.
      */
-    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
@@ -162,7 +175,9 @@ export declare class BlobUploader {
     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
@@ -181,6 +196,8 @@ export interface OffloadOptions {
     upload: UploadContext;
     tally: OffloadTally;
     memo?: MediaDigestMemo;
+    /** For tests: the length past which a long string is read in place (`LONG_STRING_UNITS`). */
+    longUnits?: number;
 }
 /**
  * A span's own attributes with each candidate placed: binary media becomes a digest, while