@hue-run/sdk 0.17.0 → 0.18.0

package/dist/client.js

@@ -1,10 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
-import { isMediaName } from "./inline-files.js";
+import { digestFormBytes, INLINE_FILE_TEXT_PER_RECORD, isMediaName } from "./inline-files.js";
 import { context, isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { defaultTextMapGetter, defaultTextMapSetter } from "@opentelemetry/api";
 import { SeverityNumber } from "@opentelemetry/api-logs";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { isAttributeValue, W3CTraceContextPropagator } from "@opentelemetry/core";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { TracerProvider } from "@opentelemetry/sdk-trace";
 import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
@@ -13,7 +13,8 @@ import { hostedServerAddresses, hostedToolActivity, hostedToolProvider, provider
 import { toolCatalogSummary } from "./tool-definitions.js";
 import { contentLimitsOf, encodeBoundedContent, encodeContent, noopSpan, safeSpan, spanSource, } from "./safety.js";
 import { TRUNCATED_KEY, withTruncatedKeys } from "./privacy.js";
-import { MAX_BLOB_BYTES } from "./blobs.js";
+import { countFallback, MAX_BLOB_BYTES, newTally } from "./blobs.js";
+import { attachmentPart, attachmentState, holdsAttachment, MAX_ATTACHMENT_DEPTH, } from "./attachment.js";
 import { createHueTransport, exportBudgetMillis, HueExportError, } from "./transport.js";
 import { verifyTrace } from "./receipt.js";
 import { sdkVersion } from "./version.js";
@@ -170,6 +171,19 @@ const OWNED_SPAN_LIMITS = {
 /** A provider tool listing's bounds before its catalog summary: one export request, 64 levels and
  * 65,536 values, as the Python SDK's content snapshot. */
 const catalogLimits = { bytes: MAX_BODY_BYTES, nodes: 65_536, depth: 64 };
+/** Whether a span attribute passed to a helper is recorded as JSON text: an attachment, a value
+ * holding one, or JSON data OpenTelemetry cannot hold as an attribute (a plain object, or an array
+ * that is not of one primitive type). */
+function recordedAsJson(value) {
+    if (holdsAttachment(value))
+        return true;
+    if (value === null || typeof value !== "object" || isAttributeValue(value))
+        return false;
+    if (Array.isArray(value))
+        return true;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
 /**
  * Hue tracing client. Helpers create spans through a private tracer and local async context, never
  * through global OpenTelemetry registration, and they fail open: capture problems are counted in
@@ -286,7 +300,10 @@ export class HueClient {
                     workspaceId: identifier(options.workspaceId ?? inherited?.workspaceId),
                     model: inherited?.model,
                 };
-                span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes: options.attributes }, active.context));
+                const { attributes, placed } = this.attributeValues(options.attributes);
+                span = this.storage.run(active, () => this.tracer.startSpan(name, { kind: options.kind ?? SpanKind.INTERNAL, attributes }, active.context));
+                for (const [key, found] of placed)
+                    this.stageAttachments(span, key, found, this.captureContent);
             }
             catch {
                 this.instrumentationFailed();
@@ -535,18 +552,127 @@ export class HueClient {
             stamp("gen_ai.provider.name", messages.provider, enclosing?.model?.provider);
             stamp("gen_ai.request.model", messages.model, enclosing?.model?.requestModel);
             stamp("gen_ai.conversation.id", undefined, enclosing?.sessionId);
-            this.logger.emit({
-                context: active,
-                severityNumber: SeverityNumber.INFO,
-                eventName: "gen_ai.client.inference.operation.details",
-                attributes,
-                body: JSON.parse(encodeContent(body, this.contentLimits())),
-            });
+            // While media may be uploaded, the body may hold files past the value cap: it is emitted
+            // when it fits the cap with each file as its digest, and export uploads the files (under
+            // `body#<pointer>` keys) or cuts the body as before. Otherwise a body over the cap is
+            // refused, as before. Each attachment is written as its digest part.
+            const limits = this.contentLimits();
+            const placed = [];
+            const place = this.placer(placed, true);
+            let text;
+            if (this.transport.holdsValues()) {
+                text = encodeContent(body, { ...limits, bytes: limits.bytes + INLINE_FILE_TEXT_PER_RECORD }, place);
+                if (Buffer.byteLength(text) > limits.bytes &&
+                    digestFormBytes(JSON.parse(text)) > limits.bytes)
+                    throw new RangeError("Content limit exceeded");
+            }
+            else
+                text = encodeContent(body, limits, place);
+            const recorded = JSON.parse(text);
+            // Attachments in the body are staged with the body until this transport admits the record;
+            // export uploads them with the media the body holds.
+            const traceId = trace.getSpanContext(active).traceId;
+            const files = this.attachmentFiles(placed, true, "logs", traceId, false);
+            if (files.length)
+                this.transport.stageLogParts(recorded, traceId, files);
+            try {
+                this.logger.emit({
+                    context: active,
+                    severityNumber: SeverityNumber.INFO,
+                    eventName: "gen_ai.client.inference.operation.details",
+                    attributes,
+                    body: recorded,
+                });
+            }
+            finally {
+                this.transport.unstageLogParts(recorded);
+            }
         }
         catch {
             this.instrumentationFailed("logs");
         }
     }
+    /** Writes each attachment as its digest part, `null` for an invalid one, collecting them. */
+    placer(placed, captureContent) {
+        return (attachment, pointer, depth) => {
+            const state = attachmentState(attachment);
+            const part = attachmentPart(state, captureContent);
+            placed.push({ state, ...(part ? { part } : {}), pointer, depth });
+            return part ?? null;
+        };
+    }
+    /**
+     * The files of the attachments a value placed that are uploaded: an invalid attachment, and
+     * an invalid name with content capture, count as instrumentation failures; nothing is uploaded
+     * without content capture or with setup credentials; a value that was `cut`, or a part deeper
+     * than Hue reads, keeps its digest part and counts as not uploaded.
+     */
+    attachmentFiles(placed, captureContent, signal, traceId, cut) {
+        const files = [];
+        const tally = newTally();
+        for (const { state, part, depth } of placed) {
+            if (!part || !state.bytes || !state.sha256) {
+                this.instrumentationFailed(signal);
+                continue;
+            }
+            if (state.invalidName && captureContent)
+                this.instrumentationFailed(signal);
+            if (!this.transport.offloadsValues() || !state.bytes.byteLength)
+                continue;
+            if (cut || depth > MAX_ATTACHMENT_DEPTH) {
+                countFallback(tally, "budget", traceId);
+                continue;
+            }
+            files.push({
+                bytes: state.bytes,
+                digest: { sha256: state.sha256, size: state.bytes.byteLength },
+                contentType: state.contentType,
+                ...(state.name === undefined ? {} : { name: state.name }),
+            });
+        }
+        if (tally.fallbacks.size)
+            this.transport.reportOffload(tally, signal);
+        return files;
+    }
+    /** Stages the attachments a span's `attribute` now holds, replacing its earlier ones. */
+    stageAttachments(span, attribute, placed, captureContent, cut = false) {
+        const traceId = span.spanContext().traceId;
+        const files = this.attachmentFiles(placed, captureContent, "traces", traceId, cut);
+        if (span.isRecording())
+            this.transport.stageParts(span, attribute, files);
+    }
+    /**
+     * Span attributes as recorded: a value that is an {@link Attachment}, an object or array holding
+     * one, or JSON data OpenTelemetry cannot hold as an attribute (an object, or an array that is not
+     * of one primitive type), becomes its JSON text with each attachment as its digest part (an
+     * invalid attachment alone is omitted); every other value is left to OpenTelemetry as given.
+     */
+    attributeValues(input) {
+        const placed = [];
+        if (!input || typeof input !== "object")
+            return { attributes: input, placed };
+        let attributes;
+        for (const [key, value] of Object.entries(input)) {
+            if (!recordedAsJson(value))
+                continue;
+            attributes ??= { ...input };
+            const found = [];
+            try {
+                const text = encodeContent(value, this.contentLimits(), this.placer(found, this.captureContent));
+                if (text === "null")
+                    delete attributes[key];
+                else
+                    attributes[key] = text;
+            }
+            catch {
+                delete attributes[key];
+                this.instrumentationFailed();
+                continue;
+            }
+            placed.push([key, found]);
+        }
+        return { attributes: attributes ?? input, placed };
+    }
     /**
      * Records the tools a model provider executed itself while producing `response`, which no
      * `hue.tool()` call saw: OpenAI Responses `mcp_call`, `web_search_call`, `file_search_call` and
@@ -799,10 +925,17 @@ export class HueClient {
         if (!this.enabled || this.closed || !this.captureContent)
             return;
         try {
+            const encode = (limits) => {
+                const placed = [];
+                return {
+                    ...encodeBoundedContent(value, limits, true, this.placer(placed, true)),
+                    placed,
+                };
+            };
             let encoded;
             if (this.transport.holdsValues())
                 try {
-                    encoded = encodeBoundedContent(value, {
+                    encoded = encode({
                         ...this.contentLimits(),
                         bytes: MAX_BLOB_BYTES,
                         nodes: MAX_RECORD_NODES,
@@ -811,8 +944,10 @@ export class HueClient {
                 catch {
                     // Past the runtime's longest string, or its memory: cut to the cap instead.
                 }
-            const { text, truncated } = encoded ?? encodeBoundedContent(value, this.contentLimits());
+            const { text, truncated, placed } = encoded ?? encode(this.contentLimits());
             span.setAttribute(key, text);
+            // The attachments the value holds are staged for upload in place of any it held before.
+            this.stageAttachments(span, key, placed, true, truncated);
             // The span's list as it stands: the application's own entries (read from the SDK span,
             // which carries its attributes; the API alone shows none) and this helper's earlier ones.
             const listed = withTruncatedKeys(span.attributes?.[TRUNCATED_KEY], this.truncatedKeys.get(span) ?? []);

package/dist/evals/client.d.ts

@@ -1,4 +1,5 @@
 import type { ProjectConnection } from "../types.js";
+import { MediaClient } from "./media.js";
 import { type AttemptConnectionBundleV2, type PrepareAttemptRequestV2 } from "./attempt.js";
 import type { ArtifactReservation, ArtifactUpload, CaseConversion, CaseConversionSummary, CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvalSet, EvalSetCase, EvalSetVersion, EvaluationItem, EvaluationRun, EvaluationRunSummary, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Evaluator, EvaluatorVersion, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Run, RunCase, Scorer, ScorerDefinition, ScorerVersion, Scoring, ScoringResultInput, ScoringResultSummary, ScoringSubject, ScoringSummary, SimulationMcpCapability, StartExecution, Subject, StoredResult, StoredScoringResult, IdentityUpdate, Tag, TaggedIdentity, UpdatedRun } from "./types.js";
 /** Connection options for {@link createEvaluationClient}. */
@@ -59,6 +60,9 @@ export declare class EvaluationClient {
     #private;
     /** Validated Hue origin. */
     readonly baseUrl: string;
+    /** Recorded media read back by digest: one file (`fetch`) or every digest part of a recorded
+     * value (`resolve`). Needs a key that may read recorded content (Read, or Read and write). */
+    readonly media: MediaClient;
     private readonly timeoutMillis;
     private readonly maxAttempts;
     constructor(options: EvaluationClientOptions);
@@ -97,7 +101,16 @@ export declare class EvaluationClient {
     getDatasetVersion(id: string): Promise<DatasetVersion>;
     /** Lists the full cases of a dataset version; use small page limits for large values. */
     listCases(id: string, page?: PageOptions): Promise<Page<DatasetCase>>;
-    /** Adds a case to a draft version using optimistic concurrency on `expectedRevision`. */
+    /**
+     * Adds a case to a draft version using optimistic concurrency on `expectedRevision`. Each of
+     * `files` given as bytes or a path is checked against the artifact policy and uploaded as a
+     * verified artifact first, under a key derived from the version, the case's `externalKey`, the
+     * role and the bytes, so sending the same case again reuses the artifact. Every file and the
+     * case itself are checked before the first upload.
+     *
+     * @throws TypeError or RangeError for `files` outside the artifact policy, or a case Hue would
+     * refuse for its fields or size, before any request.
+     */
     addCase(id: string, input: CaseWrite): Promise<{
         /** The stored case. */
         item: DatasetCase;

package/dist/evals/client.js

@@ -1,5 +1,6 @@
 import { isLoopbackHost, validateOptions } from "../config.js";
 import { json, uuid, valueBounds } from "./json.js";
+import { MediaClient } from "./media.js";
 import { attemptBindingRead, parsePrepareAttemptResultV2, parseRefreshedAttemptResultV2, parseRevocationResult, prepareAttemptInputV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
 /** Thrown for a failed evaluation API request; the message is fixed and never includes response text. */
 export class HueApiError extends Error {
@@ -149,6 +150,42 @@ function productRunFields(value, kind) {
         result.scoring = result.evaluation;
     return result;
 }
+/** The bounds of a request body as a whole: 1 MiB, with each value's node and depth bounds. */
+const REQUEST_BOUNDS = { ...valueBounds, bytes: 1024 * 1024 };
+/** A request body as it is sent: checked as JSON within `bounds`. Optional top-level fields are
+ * omitted intentionally; nested undefined remains invalid. */
+function payloadOf(body, bounds) {
+    return JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
+}
+/**
+ * Checks what a case write's fields can be checked for here, as Hue checks them: a positive
+ * integer `expectedRevision`, an `externalKey` of 1–200 UTF-16 code units of well-formed text
+ * without NUL, `inputs`, `expected` and an object `metadata` within one value's JSON bounds, and an
+ * `environmentVersionId` that is a UUID or null.
+ */
+function checkCaseWrite(input) {
+    if (!input || typeof input !== "object")
+        throw new TypeError("A case write must be an object");
+    if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 1)
+        throw new TypeError("expectedRevision must be a positive integer");
+    const key = input.externalKey;
+    if (typeof key !== "string" ||
+        !key.length ||
+        key.length > 200 ||
+        !key.isWellFormed() ||
+        key.includes("\u0000"))
+        throw new TypeError("externalKey must be 1–200 UTF-16 code units of well-formed text");
+    json(input.inputs, valueBounds);
+    if (input.expected !== undefined)
+        json(input.expected, valueBounds);
+    if (input.metadata !== undefined) {
+        if (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata))
+            throw new TypeError("metadata must be an object");
+        json(input.metadata, valueBounds);
+    }
+    if (input.environmentVersionId !== undefined && input.environmentVersionId !== null)
+        uuid(input.environmentVersionId);
+}
 /** Times a refused request is sent again before its refusal is the caller's error. */
 const REFUSAL_RETRIES = 4;
 /** A refusal asking for a longer wait fails at once rather than holding the caller. */
@@ -183,6 +220,9 @@ function refusalRetryAfter(response) {
 export class EvaluationClient {
     /** Validated Hue origin. */
     baseUrl;
+    /** Recorded media read back by digest: one file (`fetch`) or every digest part of a recorded
+     * value (`resolve`). Needs a key that may read recorded content (Read, or Read and write). */
+    media;
     #apiKey;
     timeoutMillis;
     maxAttempts;
@@ -199,6 +239,11 @@ export class EvaluationClient {
         if (!Number.isInteger(attempts) || attempts < 1 || attempts > 10)
             throw new RangeError("maxAttempts must be 1–10");
         this.maxAttempts = attempts;
+        this.media = new MediaClient({
+            baseUrl: this.baseUrl,
+            apiKey: validated.apiKey,
+            timeoutMillis: this.timeoutMillis,
+        });
     }
     /** Sends one request to Hue, again after the wait while Hue refuses it with a short
      * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
@@ -235,15 +280,12 @@ export class EvaluationClient {
                 throw new HueApiError(response.status, askedRetryAfter(response));
         }
     }
-    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }, signal, 
+    async request(method, path, body, bounds = REQUEST_BOUNDS, signal, 
     /** Overrides the retry decision `retryable` takes from the method and body. */
     idempotent) {
         // Serialized once, outside the attempts: a body this client cannot encode is a caller error
-        // no attempt fixes. Optional top-level fields are omitted intentionally; nested undefined
-        // remains invalid.
-        const payload = body === undefined
-            ? undefined
-            : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
+        // no attempt fixes.
+        const payload = body === undefined ? undefined : payloadOf(body, bounds);
         const attempts = retryable(method, body, idempotent) ? this.maxAttempts : 1;
         for (let attempt = 1;; attempt++) {
             try {
@@ -433,9 +475,31 @@ export class EvaluationClient {
     listCases(id, page) {
         return this.request("GET", `/dataset-versions/${uuid(id)}/cases${this.page(page)}`);
     }
-    /** Adds a case to a draft version using optimistic concurrency on `expectedRevision`. */
-    addCase(id, input) {
-        return this.request("POST", `/dataset-versions/${uuid(id)}/cases`, input);
+    /**
+     * Adds a case to a draft version using optimistic concurrency on `expectedRevision`. Each of
+     * `files` given as bytes or a path is checked against the artifact policy and uploaded as a
+     * verified artifact first, under a key derived from the version, the case's `externalKey`, the
+     * role and the bytes, so sending the same case again reuses the artifact. Every file and the
+     * case itself are checked before the first upload.
+     *
+     * @throws TypeError or RangeError for `files` outside the artifact policy, or a case Hue would
+     * refuse for its fields or size, before any request.
+     */
+    async addCase(id, input) {
+        // The canonical spelling: the reservation keys of uploaded files name the version.
+        const versionId = uuid(id).toLowerCase();
+        checkCaseWrite(input);
+        let body = input;
+        if (input.files !== undefined) {
+            // Loaded on use: the artifact helpers import this client.
+            const { caseFileReferences } = await import("./files.js");
+            body = {
+                ...input,
+                // The case is checked as it will be sent, with a stand-in for each upload's artifact.
+                files: await caseFileReferences(this, versionId, input, (files) => payloadOf({ ...input, files }, REQUEST_BOUNDS)),
+            };
+        }
+        return this.request("POST", `/dataset-versions/${versionId}/cases`, body);
     }
     /** Freezes a draft version at the given revision; frozen versions are immutable. */
     freezeDatasetVersion(id, expectedRevision) {

package/dist/evals/files.d.ts

@@ -1,5 +1,5 @@
 import { type EvaluationClient } from "./client.js";
-import type { CaseFile, LocalFile, OutputFile, SubjectFile } from "./types.js";
+import type { CaseFile, CaseFileReference, CaseWrite, LocalFile, OutputFile, SubjectFile } from "./types.js";
 /** Roles the target receives. Organization templates stay with grading, as in the managed protocol. */
 export declare const targetFileRoles: readonly CaseFile["role"][];
 /** Hue's artifact policy: the pilot file size and the accepted document types. */
@@ -112,5 +112,15 @@ export declare const artifactSettling: {
  * finished verifying after an earlier attempt stopped waiting.
  */
 export declare function uploadOutputFiles(client: EvaluationClient, executionId: string, files: StagedOutputFile[], save: () => Promise<void>, timing?: typeof artifactSettling): Promise<void>;
+/**
+ * The `files` of a case write as the case API takes them: references kept, and each file given
+ * as bytes or a path checked against the artifact policy (role, name, one of
+ * `outputContentTypes`, 1 byte to 25 MiB) and uploaded as a verified artifact. Every file is
+ * checked, and then `beforeUpload` is given the references with a stand-in ID for each upload,
+ * before the first upload. The reservation key names the version, the case's `externalKey`, the
+ * role and the bytes, so the same write sent again reuses its artifacts. Each artifact is pinned
+ * once with a role, even when a reference names the artifact a file was uploaded as.
+ */
+export declare function caseFileReferences(client: EvaluationClient, versionId: string, input: CaseWrite, beforeUpload?: (references: CaseFileReference[]) => void, timing?: typeof artifactSettling): Promise<CaseFileReference[]>;
 /** Project uploaded staged files as the verified local files handed to scorers. */
 export declare function localOutputFiles(files: StagedOutputFile[]): LocalFile[];

package/dist/evals/files.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { ArtifactSizeError, HueApiError } from "./client.js";
+import { uuid } from "./json.js";
 /** Roles the target receives. Organization templates stay with grading, as in the managed protocol. */
 export const targetFileRoles = [
     "source",
@@ -413,33 +414,172 @@ export async function uploadOutputFiles(client, executionId, files, save, timing
         if (file.artifactId)
             continue;
         const bytes = await verifiedBytes(file.path, file);
-        const reserved = await client.reserveArtifact({
+        file.artifactId = await publishArtifact(client, {
             idempotencyKey: `hue-sdk:${executionId}:${file.sha256}:${sha256(Buffer.from(file.filename)).slice(0, 16)}`,
             filename: file.filename,
             contentType: file.contentType,
             byteSize: file.byteSize,
             sha256: file.sha256,
-        });
-        let state = reserved.state;
-        if (state !== "ready") {
-            // A verification already running holds the uploaded bytes; Hue refuses another upload then.
-            if (reserved.copyState !== "acknowledged" && state !== "verifying") {
-                const upload = await client.requestArtifactUpload(reserved.id);
-                try {
-                    await client.uploadArtifactBytes(upload, bytes, file.contentType);
-                }
-                catch {
-                    // A lost staging acknowledgement or an immutable object already present can only be
-                    // settled by verified completion; never rewrite a final object here.
-                }
+        }, bytes, `Generated file ${file.filename}`, timing);
+        await save();
+    }
+}
+/** Reserve, stage and verify one artifact; its ID once Hue verified it. Replaying the key settles
+ * on the same artifact, including one Hue finished verifying after an earlier attempt stopped. */
+async function publishArtifact(client, declared, bytes, label, timing) {
+    const reserved = await client.reserveArtifact(declared);
+    let state = reserved.state;
+    if (state !== "ready") {
+        // A verification already running holds the uploaded bytes; Hue refuses another upload then.
+        if (reserved.copyState !== "acknowledged" && state !== "verifying") {
+            const upload = await client.requestArtifactUpload(reserved.id);
+            try {
+                await client.uploadArtifactBytes(upload, bytes, declared.contentType);
+            }
+            catch {
+                // A lost staging acknowledgement or an immutable object already present can only be
+                // settled by verified completion; never rewrite a final object here.
             }
-            state = await settleArtifact(client, reserved.id, timing);
         }
-        if (state !== "ready")
-            throw new Error(`Generated file ${file.filename} was not verified by Hue (${state})`);
-        file.artifactId = reserved.id;
-        await save();
+        state = await settleArtifact(client, reserved.id, timing);
+    }
+    if (state !== "ready")
+        throw new Error(`${label} was not verified by Hue (${state})`);
+    return reserved.id;
+}
+/** Roles a pinned case input can carry. */
+const caseFileRoles = [
+    ...targetFileRoles,
+    "org_template",
+    "evaluator_reference",
+];
+/** The most input files one case pins. */
+const MAX_CASE_FILES = 32;
+/** A case file name as the artifact API takes it: well-formed Unicode of 1–255 UTF-16 code units,
+ * as Hue counts them, without a control character or a path separator. */
+function caseFileName(name) {
+    if (typeof name !== "string" ||
+        !name.length ||
+        name.length > 255 ||
+        !name.isWellFormed() ||
+        [...name].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127 || c === "/" || c === "\\"))
+        throw new TypeError("A case file needs a well-formed filename of 1–255 UTF-16 code units without path separators or control characters");
+    return name;
+}
+/** The bytes of a case file given by path: a regular file within the size limit, read once. */
+async function caseFileBytes(path, label) {
+    if (typeof path !== "string" || !path)
+        throw new TypeError(`${label} needs bytes or a path`);
+    // A path with no file behind it, or one that cannot be read, is refused as any invalid file.
+    const unreadable = (error) => new TypeError(`${label} could not be read`, { cause: error });
+    const info = await stat(path).catch((error) => {
+        throw unreadable(error);
+    });
+    if (!info.isFile())
+        throw new TypeError(`${label} is not a regular file`);
+    if (info.size > outputFileLimits.bytes)
+        throw new RangeError(`${label} exceeds 25 MiB`);
+    return readFile(path).catch((error) => {
+        throw unreadable(error);
+    });
+}
+/** A stand-in for an artifact a case file is uploaded as, the length of a real ID. */
+const STAND_IN_ID = "00000000-0000-4000-8000-000000000000";
+/**
+ * The `files` of a case write as the case API takes them: references kept, and each file given
+ * as bytes or a path checked against the artifact policy (role, name, one of
+ * `outputContentTypes`, 1 byte to 25 MiB) and uploaded as a verified artifact. Every file is
+ * checked, and then `beforeUpload` is given the references with a stand-in ID for each upload,
+ * before the first upload. The reservation key names the version, the case's `externalKey`, the
+ * role and the bytes, so the same write sent again reuses its artifacts. Each artifact is pinned
+ * once with a role, even when a reference names the artifact a file was uploaded as.
+ */
+export async function caseFileReferences(client, versionId, input, beforeUpload = () => undefined, timing = artifactSettling) {
+    const files = input.files;
+    if (!Array.isArray(files))
+        throw new TypeError("files must be a list of case files");
+    if (files.length > MAX_CASE_FILES)
+        throw new RangeError(`A case pins at most ${MAX_CASE_FILES} files`);
+    const prepared = [];
+    const seen = new Set();
+    for (const [index, file] of files.entries()) {
+        const label = `Case file ${index + 1}`;
+        if (!file || typeof file !== "object")
+            throw new TypeError(`${label} is not a file`);
+        if (!caseFileRoles.includes(file.role))
+            throw new TypeError(`${label} has an unsupported role ${String(file.role)}`);
+        let identity;
+        if (file.artifactId !== undefined) {
+            // A reference keeps the artifact's own name and type; a file field beside it is refused
+            // rather than ignored.
+            const fields = file;
+            if (fields.filename !== undefined ||
+                fields.contentType !== undefined ||
+                fields.bytes !== undefined ||
+                fields.path !== undefined)
+                throw new TypeError(`${label} names an artifactId and a file; give one`);
+            const reference = { artifactId: uuid(file.artifactId).toLowerCase(), role: file.role };
+            prepared.push(reference);
+            identity = `artifact:${reference.artifactId}`;
+        }
+        else {
+            const filename = caseFileName(file.filename);
+            if (!outputContentTypes.includes(file.contentType))
+                throw new TypeError(`${label} has an unsupported content type ${String(file.contentType)}`);
+            if (file.bytes !== undefined && file.path !== undefined)
+                throw new TypeError(`${label} names bytes and a path; give one`);
+            if (file.bytes !== undefined && !(file.bytes instanceof Uint8Array))
+                throw new TypeError(`${label} bytes must be a Uint8Array`);
+            const bytes = file.bytes ?? (await caseFileBytes(file.path, label));
+            if (!bytes.byteLength)
+                throw new RangeError(`${label} is empty`);
+            if (bytes.byteLength > outputFileLimits.bytes)
+                throw new RangeError(`${label} exceeds 25 MiB`);
+            const digest = sha256(bytes);
+            prepared.push({
+                role: file.role,
+                filename,
+                contentType: file.contentType,
+                bytes,
+                sha256: digest,
+            });
+            identity = `file:${digest}:${file.contentType}:${filename}`;
+        }
+        const pinned = `${identity}:${file.role}`;
+        if (seen.has(pinned))
+            throw new TypeError(`${label} is pinned twice with the role ${file.role}`);
+        seen.add(pinned);
+    }
+    beforeUpload(prepared.map((item) => "artifactId" in item ? item : { artifactId: STAND_IN_ID, role: item.role }));
+    const caseKey = sha256(Buffer.from(String(input.externalKey))).slice(0, 16);
+    const references = [];
+    // A reference and an upload that settle on the same artifact are pinned once: Hue refuses an
+    // artifact pinned twice with one role.
+    const pins = new Set();
+    const pin = (reference) => {
+        const identity = `${reference.artifactId.toLowerCase()}:${reference.role}`;
+        if (pins.has(identity))
+            return;
+        pins.add(identity);
+        references.push(reference);
+    };
+    for (const item of prepared) {
+        if ("artifactId" in item) {
+            pin(item);
+            continue;
+        }
+        const artifactId = await publishArtifact(client, {
+            // The key names everything the reservation declares, so a corrected name or type reserves
+            // a new artifact instead of colliding with the earlier one.
+            idempotencyKey: `hue-sdk:case:${versionId}:${caseKey}:${item.role}:${item.sha256}:${sha256(Buffer.from(item.filename)).slice(0, 16)}:${sha256(Buffer.from(item.contentType)).slice(0, 16)}`,
+            filename: item.filename,
+            contentType: item.contentType,
+            byteSize: item.bytes.byteLength,
+            sha256: item.sha256,
+        }, item.bytes, `Case file ${item.filename}`, timing);
+        pin({ artifactId, role: item.role });
     }
+    return references;
 }
 /** Project uploaded staged files as the verified local files handed to scorers. */
 export function localOutputFiles(files) {