@ultimat3/storage 30.9.0 → 31.0.0

package/src/driver-s3-put-stream.ts

@@ -22,7 +22,7 @@ import {
   settleLostPut,
 } from './driver-s3-settle';
 import type { S3WireOptions } from './driver-s3-signed';
-import { partBytesFor } from './multipart';
+import { MAX_PART_BYTES } from './multipart';
 import type { PutStreamOptions } from './put-stream';
 import { streamLimit } from './put-stream';
 
@@ -35,6 +35,29 @@ export interface S3PutStreamInput extends Pick<S3UploadTarget, 'key' | 'refused'
   readonly stat: S3Stat;
 }
 
+/** A part's size before growth: big enough to amortise a request, small enough to hold four. */
+export const STREAM_PART_BYTES = 8 * 1024 * 1024;
+/** Parts in flight AND being filled, together: what one `putStream` holds is at most this many parts. */
+export const STREAM_PART_BUFFERS = 4;
+/** Parts per size step: the size doubles every 1,000, so 10,000 parts reach 8 TiB, past S3's 5 TiB. */
+const PARTS_PER_STEP = 1000;
+/** The first buffer for a body that may yet fit one PUT: grown by doubling, never preallocated. */
+const FIRST_BUFFER_BYTES = 64 * 1024;
+
+/**
+ * Part `n`'s size: `STREAM_PART_BYTES`, doubled every 1,000 parts, capped at S3's 5 GiB part. Never
+ * derived from the declared ceiling, which made a 1 TB `maxBytes` cut 100 MB parts for every body.
+ */
+export function streamPartBytes(partNumber: number): number {
+  // A size schedule, not a retry curve: doubled once per 1,000 parts while it stays a legal part.
+  let size = STREAM_PART_BYTES;
+  for (let past = PARTS_PER_STEP; past < partNumber; past += PARTS_PER_STEP) {
+    if (size + size > MAX_PART_BYTES) break;
+    size += size;
+  }
+  return size;
+}
+
 /** The whole body, stored — or nothing stored and the key as it was. */
 export async function putS3Stream(wire: S3WireOptions, input: S3PutStreamInput): Promise<void> {
   const { key, body, options, maxBytes, driver, refused, stat } = input;
@@ -42,30 +65,66 @@ export async function putS3Stream(wire: S3WireOptions, input: S3PutStreamInput):
   const putOptions: PutOptions = options;
   // Screened before a byte is read: a header that cannot travel fails here, not on the Create.
   const headers = objectHeaders(putOptions);
-  const partBytes = partBytesFor(maxBytes);
-  let chunks: Uint8Array[] = [];
-  let held = 0;
+  // ONE buffer per part, chunks copied in: a chunk is never held beside the part it went into.
+  let buffer = new Uint8Array(FIRST_BUFFER_BYTES);
+  let filled = 0;
   let total = 0;
   let uploadId: string | undefined;
   const etags: string[] = [];
+  const inFlight = new Set<Promise<void>>();
+  /** The first refused part, if any; later ones add nothing the caller can act on. */
+  const failures: unknown[] = [];
 
-  const sendPart = async (): Promise<void> => {
+  const dispatch = async (part: Uint8Array): Promise<void> => {
     uploadId ??= await createS3Upload(target, headers);
-    const part = new Uint8Array(Bun.concatArrayBuffers(chunks));
-    chunks = [];
-    held = 0;
-    etags.push(await uploadS3Part(target, uploadId, etags.length + 1, part));
+    const open = uploadId;
+    const partNumber = etags.length + 1;
+    etags.push('');
+    const sending = uploadS3Part(target, open, partNumber, part).then(
+      (etag) => {
+        etags[partNumber - 1] = etag;
+      },
+      (error: unknown) => {
+        failures.push(error);
+      },
+    );
+    const tracked = sending.finally(() => inFlight.delete(tracked));
+    inFlight.add(tracked);
+    // A new buffer only once one is free: in flight plus filling stays at `STREAM_PART_BUFFERS`.
+    while (inFlight.size >= STREAM_PART_BUFFERS) await Promise.race(inFlight);
+    if (failures.length > 0) throw failures[0];
+  };
+
+  const append = async (chunk: Uint8Array): Promise<void> => {
+    let at = 0;
+    while (at < chunk.byteLength) {
+      const partBytes = streamPartBytes(etags.length + 1);
+      if (filled === buffer.byteLength && buffer.byteLength < partBytes) {
+        // Still the first part: grown by doubling, so a small body never costs a whole part.
+        const grown = new Uint8Array(Math.min(partBytes, buffer.byteLength * 2));
+        grown.set(buffer.subarray(0, filled));
+        buffer = grown;
+      }
+      const taken = Math.min(chunk.byteLength - at, buffer.byteLength - filled);
+      buffer.set(chunk.subarray(at, at + taken), filled);
+      filled += taken;
+      at += taken;
+      if (filled === partBytes) {
+        filled = 0;
+        await dispatch(buffer);
+        // Allocated once a slot is free, never before: the bound is on buffers, not requests.
+        buffer = new Uint8Array(streamPartBytes(etags.length + 1));
+      }
+    }
   };
 
   try {
     await pumpBounded(body, streamLimit(driver, key, maxBytes), async (chunk) => {
-      chunks.push(chunk);
-      held += chunk.byteLength;
       total += chunk.byteLength;
-      if (held >= partBytes) await sendPart();
+      await append(chunk);
     });
-    if (uploadId === undefined) {
-      const whole = new Uint8Array(Bun.concatArrayBuffers(chunks));
+    if (uploadId === undefined && inFlight.size === 0) {
+      const whole = buffer.subarray(0, filled);
       const rethrow = (error: unknown): never => {
         throw error;
       };
@@ -75,8 +134,11 @@ export async function putS3Stream(wire: S3WireOptions, input: S3PutStreamInput):
       if (refusal !== undefined) refused(refusal);
       return;
     }
-    if (held > 0) await sendPart();
+    if (filled > 0) await dispatch(buffer.subarray(0, filled));
+    await Promise.all(inFlight);
+    if (failures.length > 0) throw failures[0];
     const open = uploadId;
+    if (open === undefined) return;
     await completeS3Upload(
       target,
       open,
@@ -89,8 +151,10 @@ export async function putS3Stream(wire: S3WireOptions, input: S3PutStreamInput):
       await settleComplete(stat, { ...target, driver }, open, sent, lost);
     });
   } catch (error) {
-    // Parts bill until they are aborted. The refusal the caller reads is the first one, so an abort
-    // that fails too is left to the bucket's lifecycle rule rather than replacing it.
+    // A part still sending would land after the abort and bill: every one settles first. The
+    // refusal the caller reads is the first one, so an abort that fails too is left to the
+    // bucket's lifecycle rule rather than replacing it.
+    await Promise.allSettled(inFlight);
     if (uploadId !== undefined) await abortS3Upload(target, uploadId).catch(() => undefined);
     throw error;
   }

package/src/driver-s3-range.ts

@@ -3,6 +3,7 @@
 // slice and its description come from one response about one version. A HEAD beside it could not
 // promise that: a write between the two, or an A → B → A overwrite of one length, slips past both.
 
+import { renderThrowable } from '@ultimat3/core';
 import type { StorageObject, StorageRead } from './driver';
 import { DEFAULT_CONTENT_TYPE } from './driver';
 import { type S3Refusal, type S3WireOptions, sendSigned } from './driver-s3-signed';
@@ -23,14 +24,20 @@ export interface S3RangeDeps {
 
 const CONTENT_RANGE = /^bytes (\d+)-(\d+)\/(\d+)$/;
 
+/** An answer refused before its body is read: the body is dropped, never left on the socket. */
+async function discardBody(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // A body that cannot be cancelled is already done: the refusal is the answer either way.
+  }
+}
+
 /**
  * The window asked, CAPPED at `maxGetBytes` before it is sent: the ceiling bounds the range, and the
  * object's size is not known until the answer — so at most the ceiling crosses the wire, and an
  * answer that shows the object went on past the cap is refused before its body is read.
  */
-const errorMessage = (thrown: unknown): string =>
-  thrown instanceof Error ? thrown.message : String(thrown);
-
 export async function readS3Range(
   wire: S3WireOptions,
   key: string,
@@ -52,13 +59,13 @@ export async function readS3Range(
   const { response } = result;
   const window = CONTENT_RANGE.exec(response.headers.get('content-range') ?? '');
   if (response.status !== 206 || window === null) {
-    await response.body?.cancel().catch(() => undefined);
+    await discardBody(response);
     return deps.unreadable(key, `the ranged GET answered ${response.status} with no byte range`);
   }
   const served: ByteRange = [Number(window[1]), Number(window[2])];
   const size = Number(window[3]);
   if (served[0] !== first || served[1] > capped) {
-    await response.body?.cancel().catch(() => undefined);
+    await discardBody(response);
     return deps.unreadable(
       key,
       `asked bytes ${first}-${capped}, answered ${served[0]}-${served[1]}`,
@@ -66,7 +73,7 @@ export async function readS3Range(
   }
   // Cut by the CAP, not by the end of the object: the range asked is over the ceiling.
   if (last > capped && size - 1 > capped) {
-    await response.body?.cancel().catch(() => undefined);
+    await discardBody(response);
     throw rangeTooLarge(deps.driver, key, [first, Math.min(last, size - 1)], deps.maxGetBytes);
   }
   let bytes: Uint8Array;
@@ -74,7 +81,7 @@ export async function readS3Range(
     bytes = new Uint8Array(await response.arrayBuffer());
   } catch (thrown) {
     // The headers came, the body broke (a reset connection): the disk's coded read failure.
-    return deps.unreadable(key, `the ranged body broke mid-read: ${errorMessage(thrown)}`);
+    return deps.unreadable(key, `the ranged body broke mid-read: ${renderThrowable(thrown)}`);
   }
   if (bytes.byteLength !== served[1] - served[0] + 1) {
     return deps.unreadable(

package/src/driver-s3-signed.ts

@@ -53,7 +53,7 @@ export interface S3Refusal {
 }
 
 export interface S3SignedRequest {
-  readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE';
+  readonly method: 'GET' | 'HEAD' | 'PUT' | 'POST' | 'DELETE';
   readonly key: string;
   /** A sub-resource such as `retention` — sent and signed as `?retention=`. */
   readonly subresource?: string | undefined;

package/src/driver-s3-stream.ts

@@ -0,0 +1,36 @@
+// Single responsibility: the s3 disk's PINNED streamed read — one signed GET carrying `If-Match`, so
+// the provider serves the revision a `stat()` described or answers 412. Bun's `S3File.stream()`
+// sends no condition, and an overwrite between the stat and the read served new bytes under the
+// old ETag and length.
+
+import { type S3Refusal, type S3WireOptions, sendSigned } from './driver-s3-signed';
+import type { ByteRange } from './range';
+
+export interface S3PinnedDeps {
+  /** The provider's refusal as the disk's coded read error (404 is not-found there). */
+  readonly refused: (refusal: S3Refusal) => never;
+  /** Another revision is at the key: the disk's `X_STORAGE_OBJECT_CHANGED`. */
+  readonly changed: () => never;
+}
+
+/** The bytes of revision `etag`, whole or `[first, last]` already clamped to the object. */
+export async function streamS3Pinned(
+  wire: S3WireOptions,
+  key: string,
+  etag: string,
+  range: ByteRange | undefined,
+  deps: S3PinnedDeps,
+): Promise<ReadableStream<Uint8Array>> {
+  const result = await sendSigned(wire, {
+    method: 'GET',
+    key,
+    headers: {
+      'if-match': etag,
+      ...(range === undefined ? {} : { range: `bytes=${range[0]}-${range[1]}` }),
+    },
+  });
+  if (!result.ok) {
+    return result.refusal.statusCode === 412 ? deps.changed() : deps.refused(result.refusal);
+  }
+  return result.response.body ?? new Blob([]).stream();
+}

package/src/driver-s3.ts

@@ -27,12 +27,13 @@ import {
   type StorageListEntry,
   type StorageObject,
   type StorageRead,
+  type StreamOptions,
   sha256Base64,
   toBytes,
 } from './driver';
 import { isAbsentObject } from './driver-s3-absent';
 import { buildClient, dated, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
-import { signedCopy } from './driver-s3-copy';
+import { copyS3 } from './driver-s3-copy-parts';
 import { needsSignedPut, readObjectLock, signedPut } from './driver-s3-lock';
 import { s3Multipart } from './driver-s3-multipart-session';
 import { s3SignedUrl } from './driver-s3-presign';
@@ -40,8 +41,9 @@ import { putS3Stream } from './driver-s3-put-stream';
 import { readS3Range } from './driver-s3-range';
 import { regionMismatch } from './driver-s3-region';
 import { settleLostPut } from './driver-s3-settle';
-import type { S3FetchLike } from './driver-s3-signed';
+import type { S3FetchLike, S3Refusal } from './driver-s3-signed';
 import { refuseUnsupportedPut } from './driver-s3-sse';
+import { streamS3Pinned } from './driver-s3-stream';
 import {
   checksumMismatch,
   deleteFailed,
@@ -53,6 +55,7 @@ import {
   readFailed,
 } from './errors';
 import { objectChanged } from './errors-promote';
+import { revisionChanged } from './errors-stream';
 import { assertObjectLockOptions, type ObjectLock } from './object-lock';
 import { assertSafeKey } from './path';
 import { assertPutStream, type PutStreamOptions } from './put-stream';
@@ -197,6 +200,14 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     };
   };
 
+  /** A pinned read's two refusals: the provider's, coded as a read, and another revision's. */
+  const pinned = (key: string, etag: string) => ({
+    refused: (refusal: S3Refusal): never => refusedRead(key)(refusal),
+    changed: (): never => {
+      throw revisionChanged(diskName, key, etag);
+    },
+  });
+
   /** The HEAD a lost write's answer is settled against, and the `.catch` of a single PUT. */
   const statOf = async (key: string) => ((await present(key)) ? statObject(key) : undefined);
   const lostPut = (key: string, bytes: Uint8Array, attributes: PutOptions | undefined) =>
@@ -313,14 +324,21 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       return { object, bytes };
     },
 
-    async stream(key: string): Promise<ReadableStream<Uint8Array>> {
+    async stream(key: string, streamOptions?: StreamOptions): Promise<ReadableStream<Uint8Array>> {
       const safe = assertSafeKey(key);
+      const etag = streamOptions?.etag;
+      if (etag !== undefined)
+        return streamS3Pinned(options, safe, etag, undefined, pinned(safe, etag));
       const file = conn().file(safe);
       if (!(await present(safe))) throw objectNotFound(diskName, safe);
       return file.stream();
     },
 
-    async streamRange(key: string, range: ByteRange): Promise<ReadableStream<Uint8Array>> {
+    async streamRange(
+      key: string,
+      range: ByteRange,
+      streamOptions?: StreamOptions,
+    ): Promise<ReadableStream<Uint8Array>> {
       const safe = assertSafeKey(key);
       assertStreamRange(DRIVER_NAME, range);
       if (!(await present(safe))) throw objectNotFound(diskName, safe);
@@ -328,6 +346,10 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       // already answered 206. Refused here it is still a status.
       const { size } = await statObject(safe);
       const [first, last] = streamedRange(DRIVER_NAME, safe, range, size);
+      const etag = streamOptions?.etag;
+      if (etag !== undefined) {
+        return streamS3Pinned(options, safe, etag, [first, last], pinned(safe, etag));
+      }
       return conn()
         .file(safe)
         .slice(first, last + 1)
@@ -335,33 +357,28 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     },
 
     /**
-     * Bytes from one key to another without a round trip through this process. Bun exposes no
-     * `CopyObject`, so the source `S3File` is handed to `write()` — Bun's own union accepts one —
-     * and the bytes move inside Bun rather than through the app's heap. That is the half of the
-     * win available today: promoting a 500MB attachment used to be `get()` + `put()`, a full GB
-     * resident in the pod. A true server-side copy needs a Bun API that does not exist in 1.3.
+     * Bytes from one key to another, server-side: ONE signed CopyObject (directive COPY), so the
+     * source's type, `Cache-Control` and `x-amz-meta-*` travel as on the local and memory disks.
+     * Past CopyObject's 5 GiB ceiling, a multipart UploadPartCopy carrying the same headers.
      */
     async copy(from: string, to: string, copyOptions?: CopyOptions): Promise<StorageObject> {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
-      // Bun's `write` takes no condition, so a revision-bound copy is the signed CopyObject.
-      if (copyOptions?.ifMatch !== undefined) {
-        const refusal = await signedCopy(options, source, destination, copyOptions.ifMatch).catch(
-          refusedWrite(destination),
-        );
-        if (refusal?.statusCode === 404) throw objectNotFound(diskName, source);
-        if (refusal?.statusCode === 412)
-          throw objectChanged(source, copyOptions.ifMatch, 'another');
-        if (refusal !== undefined) refusedWrite(destination)(refusal);
-        return statObject(destination);
-      }
-      const file = conn().file(source);
-      if (!(await present(source))) throw objectNotFound(diskName, source);
-      const stat = await file.stat().catch(refusedRead(source));
-      await conn()
-        .file(destination)
-        .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE })
-        .catch(refusedWrite(destination));
+      const ifMatch = copyOptions?.ifMatch;
+      const found = await statOf(source);
+      if (found === undefined) throw objectNotFound(diskName, source);
+      const expected = ifMatch ?? found.etag;
+      await copyS3(
+        options,
+        { source, destination, ifMatch, size: found.size, stat: statOf },
+        (refusal) => {
+          if (refusal.statusCode === 404 && refusal.code !== 'NoSuchUpload') {
+            throw objectNotFound(diskName, source);
+          }
+          if (refusal.statusCode === 412) throw objectChanged(source, expected, 'another');
+          return refusedWrite(destination)(refusal);
+        },
+      ).catch(refusedWrite(destination));
       return statObject(destination);
     },
 

package/src/driver.ts

@@ -4,7 +4,7 @@
 // and never unbounded, which is the same failure with the sender choosing the size.
 
 import type { Clock, Page } from '@ultimat3/core';
-import { assert } from '@ultimat3/core';
+import { assert, describeValue } from '@ultimat3/core';
 import { pumpBounded } from './byte-pump';
 import { putTooLarge } from './errors';
 import type { MultipartCapability } from './multipart';
@@ -172,14 +172,22 @@ export interface StorageDriver {
    * the range's length: s3 sends `Range:`, the local disk slices the file, memory slices its copy.
    */
   get(key: string, options?: GetOptions): Promise<StorageRead>;
-  /** Bytes without buffering — the only safe path for anything over a few MB. */
-  stream(key: string): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Bytes without buffering — the only safe path for anything over a few MB. `etag` pins the read
+   * to the revision a `stat()` described: another is `X_STORAGE_OBJECT_CHANGED`, never its bytes
+   * under the old validator.
+   */
+  stream(key: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
   /**
    * The bytes `[first, last]` (inclusive, clamped, as `get`'s range) with none before them read, so
    * a seek late in a film costs its window. `X_STORAGE_RANGE_UNSATISFIABLE` past the end. A method and
    * not an option on `stream`, which a third-party driver would ignore and serve the wrong bytes.
    */
-  streamRange(key: string, range: ByteRange): Promise<ReadableStream<Uint8Array>>;
+  streamRange(
+    key: string,
+    range: ByteRange,
+    options?: StreamOptions,
+  ): Promise<ReadableStream<Uint8Array>>;
   /**
    * Bytes from one key to another without them passing through this process. Idempotent in the
    * destination and non-destructive in the source: the caller deletes the source afterwards if
@@ -273,14 +281,31 @@ const isStringRecord = (value: unknown): boolean =>
  * `metadata: { n: 1n }` reached `JSON.stringify` on the local disk as a bare `TypeError`, and the
  * memory disk stored it — against the `Record<string, string>` every reader is typed on.
  */
+/** A streamed read's options: the revision it may serve. */
+export interface StreamOptions {
+  /** The etag a `stat()` answered; any other revision is refused rather than served. */
+  readonly etag?: string | undefined;
+}
+
+/** Printable ASCII: what one HTTP header value may carry, on the way in and on the way out. */
+export const HEADER_VALUE = /^[\x20-\x7e]*$/;
+
 export function assertPutOptions(driver: string, options: PutOptions | undefined): void {
   if (options === undefined) return;
   for (const name of ['contentType', 'cacheControl'] as const) {
+    const value = options[name];
     assert(
-      options[name] === undefined || typeof options[name] === 'string',
+      value === undefined || typeof value === 'string',
       `put() on the ${driver} disk was given a ${name} that is not a string`,
       `put(key, body, { ${name}: 'a string' }) — or omit ${name}`,
     );
+    // Served back as a header on every disk and SENT as one on s3: a line break is a second
+    // header, and on the signed wire a refused one read as a lost answer.
+    assert(
+      value === undefined || HEADER_VALUE.test(value),
+      `put() on the ${driver} disk was given a ${name} that cannot travel as a header (${describeValue(value)})`,
+      `put(key, body, { ${name}: 'text/plain' }) — printable ASCII, no line breaks`,
+    );
   }
   assert(
     options.metadata === undefined || isStringRecord(options.metadata),

package/src/errors-promote.ts

@@ -1,23 +1,11 @@
-// The refusals of the pending → attached move (`promoteAttachment`, `releaseQuarantine`): a key
-// still in quarantine, a key that is not a pending upload, and one an earlier call already moved.
+// The refusals of the pending → attached move (`promoteAttachment`): a key that is not a pending
+// upload, one an earlier call already moved, and one that changed while it was moved. A scanner's
+// refusals are `errors-scan.ts`'s.
 // Their codes are registered with the rest of the package's in `errors.ts`.
 
 import { renderFixLiteral } from '@ultimat3/core';
 import { StorageError } from './errors';
 
-/**
- * A key still under the quarantine prefix. The framework never scans bytes — that is the app's
- * job — so the only thing it can enforce is that nothing leaves quarantine without the app
- * saying so, which is what `promoteAttachment` refusing this key means.
- */
-export const quarantined = (key: string, orgId: string): StorageError =>
-  new StorageError({
-    code: 'X_STORAGE_QUARANTINED',
-    cause: `"${key}" is still under the quarantine prefix, so nothing has cleared it for use`,
-    fix: `scan the bytes, then releaseQuarantine({ disk, key: '${key}', orgId: '${orgId}' }) — promote the key it returns`,
-    meta: { key, orgId },
-  });
-
 /**
  * A key inside the org and outside its `pending/` prefix — most often another row's attached key
  * a client sent back. Promotion copies then deletes, so accepting it moved the victim's file onto

package/src/errors-scan.ts

@@ -0,0 +1,61 @@
+// The three refusals of a scanned promotion (`upload-scan.ts`): the scanner said infected, said
+// hold, or could not say. Their codes are registered with the rest of the package's in `errors.ts`.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+/** Never retryable with the same bytes, and never overridable by a policy: they are deleted. */
+export const uploadInfected = (
+  key: string,
+  scanner: string,
+  signature: string,
+  removed: boolean,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_UPLOAD_INFECTED',
+    cause: `the ${scanner} upload scanner found "${signature}" in "${key}"; ${
+      removed
+        ? 'the pending upload and its scan copy were deleted'
+        : 'deleting it failed, so sweepOrphans will collect what is left under pending/'
+    }`,
+    fix: 'grantUpload({ disk, orgId, request }) for a new, clean file — this one is refused for good',
+    meta: { key, scanner, signature, removed },
+  });
+
+/**
+ * The scanner rejected rather than answered. `reason` is already rendered (`renderThrowable`): a
+ * daemon's own words are the most useful thing in the cause, and an `unknown` is never interpolated.
+ */
+export const scanUnavailable = (key: string, scanner: string, reason: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_SCAN_UNAVAILABLE',
+    cause: `the ${scanner} upload scanner gave no verdict for "${key}": ${reason}`,
+    fix: `promoteAttachment({ disk, key: ${renderFixLiteral(key, "'<pending key>'")}, orgId, target, policy })   # again once the ${scanner} scanner answers — the upload is still pending; or uploadPolicy({ onScanUnavailable: 'accept' }) to promote unscanned files`,
+    meta: { key, scanner },
+  });
+
+/**
+ * The scanner answered `hold`: a decision made outside this call (a review, an async vendor scan)
+ * has not cleared the upload yet. It keeps the code the retired `quarantine: true` flow raised —
+ * the same state, a 409 — now reached through the one scan path. `reason` is the scanner's string.
+ */
+export const uploadHeld = (key: string, scanner: string, reason: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_QUARANTINED',
+    cause: `the ${scanner} upload scanner is holding "${key}" (${reason}); the upload stays pending and nothing was attached`,
+    fix: `promoteAttachment({ disk, key: ${renderFixLiteral(key, "'<pending key>'")}, orgId, target, policy })   # again once your ${scanner} scanner answers clean for this pendingKey — sweepOrphans collects it if it never does`,
+    meta: { key, scanner, reason },
+  });
+
+/**
+ * A grant aimed straight at a row's key while a scanner is installed. That key never passes through
+ * `promoteAttachment`, the one place a scan runs, so signing it would land bytes nothing scanned
+ * exactly where a row reads them.
+ */
+export const targetUnscanned = (caller: string, key: string, scanner: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TARGET_UNSCANNED',
+    cause: `${caller} was given a target ("${key}") while the ${scanner} upload scanner is installed; a targeted key never passes through promoteAttachment, so its bytes would reach the row unscanned`,
+    fix: `${caller}({ disk, orgId, request, policy })   # no target — then promoteAttachment({ disk, key, orgId, target, policy }) once the upload lands`,
+    meta: { key, scanner },
+  });

package/src/errors-stream.ts

@@ -21,6 +21,19 @@ export const streamTooLarge = (
     meta: { disk, key, bytes, maxBytes },
   });
 
+/**
+ * A streamed read pinned to a revision the key no longer holds: written between the `stat()` whose
+ * etag, size and type a response was built on and the read of its bytes. Same code as a promotion
+ * that met another revision, for the same reason.
+ */
+export const revisionChanged = (disk: string, key: string, expected: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_OBJECT_CHANGED',
+    cause: `"${key}" on the ${disk} disk was overwritten after it was described as ${expected}, so its bytes are another revision's and were not served`,
+    fix: `const object = await disk.stat(${keyArg(key)}); await disk.stream(${keyArg(key)}, { etag: object.etag })   # describe it again, then read that revision`,
+    meta: { disk, key, expected },
+  });
+
 /** `rangeUnsatisfiable` for a call that holds no size: the next step is learning it. */
 export const streamRangeUnsatisfiable = (
   disk: string,

package/src/errors-variant.ts

@@ -0,0 +1,40 @@
+// The refusals of `variant()` (`image-variant.ts`). A source that is no raster and a driver that
+// answered another encoding are core's `X_IMAGE_UNSUPPORTED`, as every other image refusal here is;
+// a source overwritten mid-transform is storage's `X_STORAGE_OBJECT_CHANGED`.
+
+import { type ImageUnsupportedError, imageUnsupported, renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+export const notARaster = (key: string, contentType: string): ImageUnsupportedError =>
+  imageUnsupported(
+    `"${key}" is stored as ${contentType}, which is not a raster image, so it has no width to resize to`,
+    `await disk.stat(${renderFixLiteral(key, "'<key>'")})   # variant() takes a png, jpeg, webp, gif or avif source: check its contentType, or serve it as-is`,
+    { key, contentType },
+  );
+
+export const variantFormatUnknown = (key: string, contentType: string): ImageUnsupportedError =>
+  imageUnsupported(
+    `"${key}" is a ${contentType} source and no variant format was named, so no key can say what the transform will answer`,
+    `variant(${renderFixLiteral(key, "'<key>'")}, { disk, images, width, format: 'webp' })`,
+    { key, contentType },
+  );
+
+export const driverEncodingMismatch = (
+  key: string,
+  driver: string,
+  expected: string,
+  actual: string,
+): ImageUnsupportedError =>
+  imageUnsupported(
+    `the ${driver} image driver answered ${actual} for "${key}", whose key names ${expected}, so the bytes would be served under the wrong type`,
+    `variant(${renderFixLiteral(key, "'<key>'")}, { disk, images, width, format: '<the format the ${driver} driver produces>' })   # or make its transform() honour request.format`,
+    { key, driver, expected, actual },
+  );
+
+export const variantSourceChanged = (key: string, expected: string, actual: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_OBJECT_CHANGED',
+    cause: `"${key}" was overwritten while its variant was being made (etag ${expected} → ${actual}), so the bytes cannot be filed under either revision`,
+    fix: `variant(${renderFixLiteral(key, "'<key>'")}, { disk, images, width }) again — it keys the variant by the new revision`,
+    meta: { key, expected, actual },
+  });

package/src/errors.ts

@@ -39,6 +39,9 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_MULTIPART_UNSUPPORTED',
   'X_STORAGE_UPLOAD_UNKNOWN',
   'X_STORAGE_PARTS_INVALID',
+  'X_STORAGE_UPLOAD_INFECTED',
+  'X_STORAGE_SCAN_UNAVAILABLE',
+  'X_STORAGE_TARGET_UNSCANNED',
 ] as const;
 
 /**
@@ -89,6 +92,9 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_MULTIPART_UNSUPPORTED: 'this disk cannot take an upload in parts',
   X_STORAGE_UPLOAD_UNKNOWN: 'no open multipart upload has that id',
   X_STORAGE_PARTS_INVALID: 'the parts named do not match the parts stored',
+  X_STORAGE_UPLOAD_INFECTED: 'the upload scanner found malware in the file',
+  X_STORAGE_SCAN_UNAVAILABLE: 'the upload scanner could not give a verdict',
+  X_STORAGE_TARGET_UNSCANNED: 'a targeted upload grant would bypass the upload scanner',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws