@hue-run/sdk 0.18.2 → 0.19.0

package/dist/cli/langfuse.d.ts

@@ -86,12 +86,15 @@ export declare function readObservation(value: unknown): LangfuseObservation | u
 /** A v1 trace from an API answer, or undefined when it lacks an id or timestamp. */
 export declare function readTrace(value: unknown): LangfuseTrace | undefined;
 /** An answer read whole: its status and body, or `tooLarge` for a body past the bound. */
-type Answer = {
+type Answer = ({
     status: number;
     body: Buffer;
 } | {
     status: number;
     tooLarge: true;
+}) & {
+    /** A redirect's `Location`, which no request follows itself. */
+    location?: string;
 };
 /** Reads one Langfuse project through its public API with Basic authentication. */
 export declare class LangfuseApi {
@@ -105,9 +108,10 @@ export declare class LangfuseApi {
     /**
      * One GET with retries: a rate limit (HTTP 429) is waited out for as long as its `Retry-After`
      * asks (up to 15 minutes, ten times in a row), and a connection failure, a timeout or a 5xx is
-     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). An
-     * authenticated request never follows a redirect, so the keys go only to the configured host;
-     * `authenticated` is false for a presigned media download, which carries no Langfuse keys.
+     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). No
+     * redirect is followed (its `Location` is answered), so the keys go only to the configured host
+     * and a media download reaches only links {@link LangfuseApi.media} checked; `authenticated` is
+     * false for a presigned media download, which carries no Langfuse keys.
      */
     get(url: URL, authenticated?: boolean, maxBytes?: number, timeoutMs?: number): Promise<Answer>;
     /** A GET of `path` under the API, answered with JSON; refusals of the keys are fatal. */
@@ -131,10 +135,22 @@ export declare class LangfuseApi {
     /**
      * A media file's bytes through `GET /api/public/media/{id}` and the download link it answers
      * (fetched without the Langfuse keys): `missing` when Langfuse holds no bytes for it (no record,
-     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}.
+     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}. The link
+     * and each redirect from it must pass {@link refusedDownload}; one that does not fails the file.
      */
     media(id: string): Promise<Uint8Array | "missing" | "tooLarge">;
 }
+/** Whether an IP address is one {@link INTERNAL_ADDRESSES} holds; false for anything else. */
+export declare function isInternalAddress(address: string): boolean;
+/**
+ * Why a media download link is refused, or undefined when it may be fetched: it must be HTTPS
+ * (plain HTTP only to this machine), at most 8192 characters, without credentials or a fragment,
+ * and name a host whose every address is public, unless it names the configured Langfuse host or
+ * that host is on this machine. Langfuse chooses the link, so this keeps a hostile or compromised
+ * deployment from sending requests to this machine's network. The name's lookup gives up after a
+ * minute or once `signal` stops the import.
+ */
+export declare function refusedDownload(url: URL, langfuse: URL, signal: AbortSignal): Promise<string | undefined>;
 /** The OpenTelemetry trace id of a Langfuse trace: its own id when it is one (32 lowercase hex
  * digits, as the Langfuse OpenTelemetry SDKs write), otherwise one derived from it by SHA-256, so
  * the same trace always takes the same id. */

package/dist/cli/langfuse.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
 import { SpanKind, SpanStatusCode, TraceFlags, } from "@opentelemetry/api";
-import { MAX_CONTENT_BYTES, MAX_FILE_DATA_BYTES } from "../config.js";
+import { MAX_CONTENT_BYTES, MAX_FILE_DATA_BYTES, isLoopbackHost } from "../config.js";
 import { BLOBS_KEY, MAX_BLOB_ENTRIES, blobEntry, newTally, offloadAttributes, } from "../blobs.js";
 import { digestPart, isMediaContentType, mayInlineFiles, mediaIn, placedMediaText, readerParses, } from "../inline-files.js";
 import { sdkVersion } from "../version.js";
@@ -16,6 +18,10 @@ import { sdkVersion } from "../version.js";
 const REQUEST_TIMEOUT_MS = 60_000;
 /** A media file download's deadline: up to 25 MiB over a slow link. */
 const DOWNLOAD_TIMEOUT_MS = 300_000;
+/** Redirects a media download follows, each to a link checked as the first one was. */
+const MAX_DOWNLOAD_REDIRECTS = 5;
+/** The longest media download link accepted, as the Python SDK's media client accepts. */
+const MAX_LINK_LENGTH = 8192;
 /** The largest answer read from the API. Langfuse Cloud answers at most 5 MB; a larger answer is
  * asked for again in smaller pages. */
 const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
@@ -210,9 +216,10 @@ export class LangfuseApi {
     /**
      * One GET with retries: a rate limit (HTTP 429) is waited out for as long as its `Retry-After`
      * asks (up to 15 minutes, ten times in a row), and a connection failure, a timeout or a 5xx is
-     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). An
-     * authenticated request never follows a redirect, so the keys go only to the configured host;
-     * `authenticated` is false for a presigned media download, which carries no Langfuse keys.
+     * tried again after 1, 2, 4, 8 and 16 seconds (or its `Retry-After`, up to a minute). No
+     * redirect is followed (its `Location` is answered), so the keys go only to the configured host
+     * and a media download reaches only links {@link LangfuseApi.media} checked; `authenticated` is
+     * false for a presigned media download, which carries no Langfuse keys.
      */
     async get(url, authenticated = true, maxBytes = MAX_RESPONSE_BYTES, timeoutMs = REQUEST_TIMEOUT_MS) {
         let failures = 0;
@@ -227,9 +234,7 @@ export class LangfuseApi {
                         "user-agent": `hue-sdk-typescript/${sdkVersion} hue-import`,
                         ...(authenticated ? { authorization: this.authorization } : {}),
                     },
-                    // The keys go only to the configured host; a presigned download carries none and may
-                    // be redirected by its store.
-                    redirect: authenticated ? "manual" : "follow",
+                    redirect: "manual",
                     signal: AbortSignal.any([this.connection.signal, AbortSignal.timeout(timeoutMs)]),
                 });
             }
@@ -258,6 +263,11 @@ export class LangfuseApi {
                 failures++;
                 continue;
             }
+            const location = status >= 300 && status < 400 ? response.headers.get("location") : null;
+            if (location !== null) {
+                await response.body?.cancel().catch(() => undefined);
+                return { status, body: Buffer.alloc(0), location };
+            }
             let body;
             try {
                 body = await readBounded(response, maxBytes);
@@ -478,7 +488,8 @@ export class LangfuseApi {
     /**
      * A media file's bytes through `GET /api/public/media/{id}` and the download link it answers
      * (fetched without the Langfuse keys): `missing` when Langfuse holds no bytes for it (no record,
-     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}.
+     * no link, or a link whose object is gone), `tooLarge` past {@link MAX_FILE_DATA_BYTES}. The link
+     * and each redirect from it must pass {@link refusedDownload}; one that does not fails the file.
      */
     async media(id) {
         const answer = await this.json(`/api/public/media/${encodeURIComponent(id)}`, {});
@@ -499,16 +510,112 @@ export class LangfuseApi {
         }
         if (url.protocol !== "https:" && url.protocol !== "http:")
             return "missing";
-        const download = await this.get(url, false, MAX_FILE_DATA_BYTES, DOWNLOAD_TIMEOUT_MS);
-        if ("tooLarge" in download)
-            return download.status === 200 ? "tooLarge" : "missing";
-        if (download.status === 200)
-            return new Uint8Array(download.body);
-        if ([403, 404, 410].includes(download.status))
-            return "missing";
-        throw new LangfuseError(`The media download answered HTTP ${download.status}`);
+        const langfuse = new URL(this.connection.baseUrl);
+        for (let redirects = 0;; redirects++) {
+            const refused = await refusedDownload(url, langfuse, this.connection.signal);
+            this.stopped();
+            if (refused)
+                throw new LangfuseError(`Langfuse named a media download link that ${refused}`);
+            const download = await this.get(url, false, MAX_FILE_DATA_BYTES, DOWNLOAD_TIMEOUT_MS);
+            if (download.location !== undefined) {
+                if (redirects === MAX_DOWNLOAD_REDIRECTS)
+                    throw new LangfuseError("The media download redirected too many times");
+                try {
+                    url = new URL(download.location, url);
+                }
+                catch {
+                    throw new LangfuseError("The media download redirected to something other than a URL");
+                }
+                continue;
+            }
+            if ("tooLarge" in download)
+                return download.status === 200 ? "tooLarge" : "missing";
+            if (download.status === 200)
+                return new Uint8Array(download.body);
+            if ([403, 404, 410].includes(download.status))
+                return "missing";
+            throw new LangfuseError(`The media download answered HTTP ${download.status}`);
+        }
     }
 }
+/** Addresses a media download may not reach: this machine, private networks, link-local
+ * (cloud metadata), shared, benchmarking, multicast and reserved ranges. IPv4-mapped IPv6
+ * addresses are checked as their IPv4 address. */
+const INTERNAL_ADDRESSES = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["224.0.0.0", 3],
+])
+    INTERNAL_ADDRESSES.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["64:ff9b::", 96],
+    ["fc00::", 7],
+    ["fe80::", 10],
+    ["fec0::", 10],
+    ["ff00::", 8],
+])
+    INTERNAL_ADDRESSES.addSubnet(network, prefix, "ipv6");
+/** Whether an IP address is one {@link INTERNAL_ADDRESSES} holds; false for anything else. */
+export function isInternalAddress(address) {
+    const version = isIP(address);
+    return version !== 0 && INTERNAL_ADDRESSES.check(address, version === 4 ? "ipv4" : "ipv6");
+}
+/**
+ * Why a media download link is refused, or undefined when it may be fetched: it must be HTTPS
+ * (plain HTTP only to this machine), at most 8192 characters, without credentials or a fragment,
+ * and name a host whose every address is public, unless it names the configured Langfuse host or
+ * that host is on this machine. Langfuse chooses the link, so this keeps a hostile or compromised
+ * deployment from sending requests to this machine's network. The name's lookup gives up after a
+ * minute or once `signal` stops the import.
+ */
+export async function refusedDownload(url, langfuse, signal) {
+    if (url.href.length > MAX_LINK_LENGTH)
+        return "is too long";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname)))
+        return "does not use https";
+    if (url.username || url.password || url.hash)
+        return "carries credentials or a fragment";
+    if (isLoopbackHost(langfuse.hostname) || url.hostname === langfuse.hostname)
+        return undefined;
+    const host = url.hostname.replace(/^\[|\]$/gu, "");
+    const named = host === "localhost" || host.endsWith(".localhost");
+    // shortcut: the name is resolved apart from the request's own lookup, so a host that answers a
+    // second lookup differently (DNS rebinding) is not caught; pin the lookup if fetch gains a hook.
+    let addresses;
+    try {
+        addresses =
+            named || isIP(host)
+                ? [named ? "127.0.0.1" : host]
+                : await resolved(host, AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]));
+    }
+    catch {
+        return "names a host that could not be resolved";
+    }
+    if (addresses.length === 0 || addresses.some(isInternalAddress))
+        return "names an address on this machine or a private network";
+    return undefined;
+}
+/** Every address `host` resolves to; rejects once `signal` aborts, since a lookup cannot be
+ * cancelled. */
+function resolved(host, signal) {
+    return new Promise((resolve, reject) => {
+        const stop = () => reject(new Error("The lookup was abandoned"));
+        if (signal.aborted)
+            return stop();
+        signal.addEventListener("abort", stop, { once: true });
+        lookup(host, { all: true }).then((entries) => resolve(entries.map((entry) => entry.address)), reject);
+    });
+}
 // ---------------------------------------------------------------------------------------------
 // Conversion
 // ---------------------------------------------------------------------------------------------

package/dist/client.d.ts

@@ -51,8 +51,9 @@ export declare class HueClient {
     private ownedProviders?;
     private closed;
     private shutdownPromise?;
-    private flushPromise?;
-    private safeFlushPromise?;
+    /** The latest flush while it still sends its records (`sent`, which the next flush's send
+     * follows), and the safe result that joined it. */
+    private sending?;
     private safeShutdownPromise?;
     constructor(options: HueOptions | ExistingHueProviders);
     /**
@@ -206,22 +207,25 @@ export declare class HueClient {
     /**
      * Safe for finally blocks; preserves the application's result or original exception. When its
      * budget runs out while the client's own transport holds records for a receiver that limited
-     * the rate, the hold ends: those records are reported lost to the rate limit, and the hold no
-     * longer keeps the process running.
+     * the rate, or still uploads values its records listed, the hold and the uploads end: those
+     * records are reported lost to the rate limit, the uploads counted as failed (their records keep
+     * their entries), and neither keeps the process running.
      */
     shutdownSafe(options?: SafeLifecycleOptions): Promise<SafeLifecycleResult>;
     private safeLifecycle;
     /**
-     * Drains the trace and log providers and waits for Hue's acknowledgements. Each caller gets a
-     * fresh serialized drain that includes records emitted before its call.
+     * Drains the trace and log providers and waits for Hue's acknowledgements, then for the uploads
+     * queued so far. Each caller gets a fresh drain that includes records emitted before its call;
+     * its records are sent after an earlier drain's records, never after that drain's uploads.
      *
      * @throws HueExportError when this drain observed a new rejection, delivery failure, drop or
      * invalid record; its `issues` and `report` are sanitized counts, never server text.
      */
     flush(): Promise<ExportReport>;
-    private flushOnce;
+    private flushProviders;
     /**
      * Flushes, then shuts down the providers this client owns; borrowed providers are left running.
+     * Like {@link flush}, it waits for queued uploads after the records are sent.
      * Idempotent: later calls return the same promise, and later helper calls only run their callbacks.
      *
      * @throws HueExportError when the final flush observed new failures; owned providers are still released.

package/dist/client.js

@@ -219,8 +219,9 @@ export class HueClient {
     ownedProviders;
     closed = false;
     shutdownPromise;
-    flushPromise;
-    safeFlushPromise;
+    /** The latest flush while it still sends its records (`sent`, which the next flush's send
+     * follows), and the safe result that joined it. */
+    sending;
     safeShutdownPromise;
     constructor(options) {
         if ("transport" in options) {
@@ -1065,24 +1066,25 @@ export class HueClient {
     }
     /** Production lifecycle path: never rejects; timeouts do not cancel borrowed provider work. */
     flushSafe(options = {}) {
-        if (this.safeFlushPromise)
-            return this.safeFlushPromise;
-        const work = this.flushPromise ?? this.flush();
+        // A flush still sending its records is joined, so repeated timeouts do not accumulate
+        // promises against a hung borrowed provider. Once it sent them, a new flush sends the
+        // caller's own records instead of waiting on the earlier flush's uploads.
+        if (this.sending?.safe)
+            return this.sending.safe;
+        const work = this.sending?.work ?? this.flush();
+        // An invalid budget returns before the result awaits the flush: its failure is still handled.
+        void work.catch(() => { });
         const result = this.safeLifecycle(() => work, options);
-        this.safeFlushPromise = result;
-        const clear = () => {
-            this.safeFlushPromise = undefined;
-        };
-        // Retain the timed-out result until its underlying drain settles. Repeated
-        // timeouts must not accumulate promises against a hung borrowed provider.
-        void work.then(clear, clear);
+        if (this.sending?.work === work)
+            this.sending.safe = result;
         return result;
     }
     /**
      * Safe for finally blocks; preserves the application's result or original exception. When its
      * budget runs out while the client's own transport holds records for a receiver that limited
-     * the rate, the hold ends: those records are reported lost to the rate limit, and the hold no
-     * longer keeps the process running.
+     * the rate, or still uploads values its records listed, the hold and the uploads end: those
+     * records are reported lost to the rate limit, the uploads counted as failed (their records keep
+     * their entries), and neither keeps the process running.
      */
     shutdownSafe(options = {}) {
         if (this.safeShutdownPromise)
@@ -1130,8 +1132,9 @@ export class HueClient {
         }
     }
     /**
-     * Drains the trace and log providers and waits for Hue's acknowledgements. Each caller gets a
-     * fresh serialized drain that includes records emitted before its call.
+     * Drains the trace and log providers and waits for Hue's acknowledgements, then for the uploads
+     * queued so far. Each caller gets a fresh drain that includes records emitted before its call;
+     * its records are sent after an earlier drain's records, never after that drain's uploads.
      *
      * @throws HueExportError when this drain observed a new rejection, delivery failure, drop or
      * invalid record; its `issues` and `report` are sanitized counts, never server text.
@@ -1139,25 +1142,31 @@ export class HueClient {
     flush() {
         // Each caller needs a drain after its own preceding span/log emissions.
         // Joining an earlier drain can acknowledge records that were not in its batch.
+        // Only the sends are serialized: each flush then waits on its own for the uploads queued so
+        // far, so a later flush's records never wait behind an earlier flush's uploads.
         const from = this.transport.getFailureSequence();
-        const drain = async () => {
-            const report = await this.flushOnce();
+        const start = () => this.transport.flushRecords(() => this.flushProviders());
+        const flushing = (this.sending?.sent ?? Promise.resolve()).then(start, start);
+        const sent = flushing.then(({ sent }) => sent);
+        const next = flushing
+            .then(({ report }) => report)
+            .then((report) => {
             if (this.transport.getFailureSequence() !== from)
                 throw new HueExportError(this.transport
                     .getIssues()
                     .filter((issue) => issue.sequence > from && issue.kind !== "warning"), report);
             return report;
-        };
-        const next = (this.flushPromise ?? Promise.resolve()).then(drain, drain);
-        this.flushPromise = next;
+        });
+        const sending = { work: next, sent };
+        this.sending = sending;
         const clear = () => {
-            if (this.flushPromise === next)
-                this.flushPromise = undefined;
+            if (this.sending === sending)
+                this.sending = undefined;
         };
-        void next.then(clear, clear);
+        void sent.then(clear, clear);
         return next;
     }
-    async flushOnce() {
+    async flushProviders() {
         // Providers this client owns wait as long as an export may take, a rate-limit hold included,
         // instead of OpenTelemetry's 30 s; borrowed providers keep their own budget.
         const owned = this.ownedProviders;
@@ -1169,10 +1178,10 @@ export class HueClient {
         for (const [index, result] of results.entries())
             if (result.status === "rejected")
                 this.transport.issue(index === 0 ? "traces" : "logs", "failed", 0, "OpenTelemetry provider flush failed");
-        return this.transport.flush();
     }
     /**
      * Flushes, then shuts down the providers this client owns; borrowed providers are left running.
+     * Like {@link flush}, it waits for queued uploads after the records are sent.
      * Idempotent: later calls return the same promise, and later helper calls only run their callbacks.
      *
      * @throws HueExportError when the final flush observed new failures; owned providers are still released.

package/dist/large-media.d.ts

@@ -24,10 +24,18 @@ export declare const WINDOW_UNITS: number;
  * reused for the next one, so a reader is done with each slice before it asks for the next. */
 export interface ByteSource {
     readonly size: number;
+    /** The strings the source keeps alive while it is held, each whole; absent for one read from
+     * elsewhere. */
+    readonly held?: readonly HeldText[];
     chunks(): Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
     /** Set when the latest read found the source no longer holds the bytes it was recorded with. */
     changed?: boolean;
 }
+/** A string sources keep alive, as its two bytes a code unit: a slice read in place keeps the
+ * whole string, so the sources that read one share its {@link HeldText}, charged once. */
+export interface HeldText {
+    readonly bytes: number;
+}
 /** Whether a value is a {@link ByteSource}. */
 export declare function isByteSource(value: unknown): value is ByteSource;
 /** How the bytes of a long string are read from its text. */
@@ -42,6 +50,8 @@ export interface LongText {
     kind: LongKind;
     /** A `data:` URL's header, between `data:` and its comma. */
     header?: string;
+    /** `text` whole, shared by every long string read from it. */
+    held: HeldText;
 }
 /** A media value read in place, with the long strings its stand-ins name. Its `source` is the
  * skeleton: placing its files edits the skeleton, and {@link placedLargeText} writes the long
@@ -67,8 +77,10 @@ export declare function readLargeMediaText(key: string, text: string, longUnits?
  * remainder is never held in two copies.
  */
 export declare class JoinedText {
+    private readonly held;
     private readonly pieces;
-    constructor(pieces: [string, number, number][]);
+    /** `held`: the strings the pieces are cut from, which the text keeps alive whole. */
+    constructor(pieces: [string, number, number][], held: readonly HeldText[]);
     /** The text a window at a time, never between the halves of a surrogate pair. */
     windows(): Generator<string>;
     /** The first `units` code units. */

package/dist/large-media.js

@@ -63,7 +63,7 @@ async function strictBase64(text, start, end) {
  * is parsed with the rest of the value (a percent-escaped `data:` URL included); a string literal
  * whose header holds a control character, which no JSON does, is left for the parse to refuse.
  */
-async function classify(text, start, end, raw = false) {
+async function classify(text, start, end, held, raw = false) {
     if (text.startsWith("data:", start)) {
         // The comma is looked for within the string and the header's bound only.
         const found = text
@@ -77,11 +77,11 @@ async function classify(text, start, end, raw = false) {
             return undefined;
         if (!(await strictBase64(text, comma + 1, end)))
             return undefined;
-        return { text, start, end, data: comma + 1, kind: "dataBase64", header };
+        return { text, start, end, data: comma + 1, kind: "dataBase64", header, held };
     }
     if (!(await strictBase64(text, start, end)))
         return undefined;
-    return { text, start, end, data: start, kind: "base64" };
+    return { text, start, end, data: start, kind: "base64", held };
 }
 /** The stand-in for a long string in the skeleton: its kind kept (base64 and its first 16
  * characters, which name an audio container; a `data:` URL's header), longer than any label, and
@@ -139,7 +139,7 @@ async function find(text, character, from, to) {
  * unterminated (text that is no JSON) ends the scan; the skeleton then holds the rest as recorded
  * and fails to parse. The scan reads at most a window of the text in one synchronous step.
  */
-async function skeletonOf(text, longUnits) {
+async function skeletonOf(text, longUnits, held) {
     const nonce = randomBytes(16).toString("hex");
     const long = new Map();
     const replaced = [];
@@ -193,7 +193,7 @@ async function skeletonOf(text, longUnits) {
         // Only a value: a key stays as it is.
         const found = escaped || close - open - 1 <= longUnits || text.charCodeAt(space(text, at)) === 0x3a
             ? undefined
-            : await classify(text, open + 1, close);
+            : await classify(text, open + 1, close, held);
         if (found) {
             const stub = standIn(found, `${nonce}${long.size.toString(16).padStart(8, "0")}`);
             long.set(stub, found);
@@ -222,11 +222,12 @@ async function skeletonOf(text, longUnits) {
  */
 export async function readLargeMediaText(key, text, longUnits = LONG_STRING_UNITS) {
     const reading = readingOf(key);
+    const held = { bytes: text.length * 2 };
     /** Text that is no JSON is the file itself when it is one long base64 `data:` URL; other text
      * is read as `readMediaText` reads it, within the 8 Mi bound. */
     const whole = async () => {
         const found = text.length > longUnits && text.startsWith("data:")
-            ? await classify(text, 0, text.length, true)
+            ? await classify(text, 0, text.length, held, true)
             : undefined;
         if (!found)
             return text.length > MAX_INLINE_FILE_TEXT
@@ -237,7 +238,7 @@ export async function readLargeMediaText(key, text, longUnits = LONG_STRING_UNIT
         return { ...mediaIn(stub), long: new Map([[stub, found]]), nonce, order: [stub] };
     };
     const json = async (check) => {
-        const skeleton = await skeletonOf(text, longUnits);
+        const skeleton = await skeletonOf(text, longUnits, held);
         if (!skeleton)
             return undefined;
         const parsed = JSON.parse(skeleton.text);
@@ -279,8 +280,11 @@ export async function readLargeMediaText(key, text, longUnits = LONG_STRING_UNIT
  * remainder is never held in two copies.
  */
 export class JoinedText {
+    held;
     pieces;
-    constructor(pieces) {
+    /** `held`: the strings the pieces are cut from, which the text keeps alive whole. */
+    constructor(pieces, held) {
+        this.held = held;
         this.pieces = pieces.filter(([, start, end]) => end > start);
     }
     /** The text a window at a time, never between the halves of a surrogate pair. */
@@ -329,6 +333,7 @@ export class JoinedText {
         const windows = () => this.windows();
         return {
             size,
+            held: this.held,
             *chunks() {
                 const buffer = Buffer.allocUnsafe(WINDOW_UNITS * 3);
                 for (const window of windows())
@@ -350,6 +355,7 @@ export async function placedLargeText(media) {
     // One forward scan for the stand-ins' shared nonce finds each one left, in order, by the index
     // its tag carries: linear in the text however many there are, a window at a time.
     const pieces = [];
+    const held = new Set([{ bytes: edited.length * 2 }]);
     let from = 0;
     let turn = 0;
     for (let at = edited.indexOf(media.nonce); at !== -1; at = edited.indexOf(media.nonce, at + 1)) {
@@ -365,21 +371,23 @@ export async function placedLargeText(media) {
             continue;
         const long = media.long.get(stub);
         pieces.push([edited, from, start], [long.text, long.start, long.end]);
+        held.add(long.held);
         from = start + stub.length;
         at = from - 1;
     }
     if (!pieces.length)
         return edited;
     pieces.push([edited, from, edited.length]);
-    return new JoinedText(pieces);
+    return new JoinedText(pieces, [...held]);
 }
 /** Base64 from `start` to `end` of `text` (strict, padded to a multiple of four), decoded a window
- * at a time into one buffer each read reuses. */
-function base64Source(text, start, end) {
+ * at a time into one buffer each read reuses. `held` is `text` whole. */
+function base64Source(text, start, end, held) {
     const length = end - start;
     const pad = (text.charCodeAt(end - 1) === 0x3d ? 1 : 0) + (text.charCodeAt(end - 2) === 0x3d ? 1 : 0);
     return {
         size: (length / 4) * 3 - pad,
+        held: [held],
         *chunks() {
             const buffer = Buffer.allocUnsafe((WINDOW_UNITS / 4) * 3);
             for (let at = start; at < end; at += WINDOW_UNITS) {
@@ -392,7 +400,7 @@ function base64Source(text, start, end) {
 /** The bytes of a file whose content is a long string, as `mediaBytes` reads them: a field its
  * convention declares base64 decoded, base64 text decoded (`bareBase64`), a base64 `data:` URL. */
 export function longFileBytes(file, long) {
-    const source = base64Source(long.text, long.data, long.end);
+    const source = base64Source(long.text, long.data, long.end, long.held);
     if (long.kind === "base64")
         return {
             size: source.size,