@ultimat3/storage 30.8.0 → 31.0.0

package/src/grant.ts

@@ -7,13 +7,15 @@
 import type { Clock } from '@ultimat3/core';
 import { finiteCount, systemClock } from '@ultimat3/core';
 import type { AttachmentTarget } from './attachment';
-import { attachmentKey, pendingKey, quarantineKey, uploadName } from './attachment';
+import { attachmentKey, pendingKey, uploadName } from './attachment';
 import type { StorageDriver } from './driver';
 import { contentTypeNotAllowed, tooLarge } from './errors';
+import { targetUnscanned } from './errors-scan';
 import { uploadSizeUndeclared } from './errors-stream';
 import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
 import type { UploadPolicy } from './upload';
 import { normalizeContentType, uploadPolicy } from './upload';
+import { uploadScanner } from './upload-scanner';
 
 export interface UploadRequest {
   /** The client's own name for the file. Used for its extension and nothing else. */
@@ -46,14 +48,12 @@ export interface GrantUploadInput {
   readonly orgId: string;
   readonly request: UploadRequest;
   readonly policy?: UploadPolicy | undefined;
-  /** Absent means the row does not exist yet, so the key lands under `pending/`. */
-  readonly target?: AttachmentTarget | undefined;
   /**
-   * Land the bytes under `pending/quarantine/` instead, so nothing can promote them until the
-   * app's scan job calls `releaseQuarantine`. Only meaningful without a `target`: an upload
-   * aimed straight at a row has no promotion step left to gate.
+   * Absent means the row does not exist yet, so the key lands under `pending/`. Refused while an
+   * `uploadScanner` is installed (`X_STORAGE_TARGET_UNSCANNED`): a targeted key skips
+   * `promoteAttachment`, the one place a scan runs.
    */
-  readonly quarantine?: boolean | undefined;
+  readonly target?: AttachmentTarget | undefined;
   readonly expiresInMs?: number | undefined;
   readonly clock?: Clock | undefined;
   /** Determinism seam for tests. Defaults to `crypto.randomUUID()`. */
@@ -82,9 +82,14 @@ export function decideGrant(caller: string, input: GrantUploadInput): GrantedUpl
     (input.uploadId ?? (() => crypto.randomUUID()))(),
     input.request.filename,
   );
-  const pending =
-    input.quarantine === true ? quarantineKey(input.orgId, name) : pendingKey(input.orgId, name);
-  const key = input.target === undefined ? pending : attachmentKey(input.orgId, input.target, name);
+  const key =
+    input.target === undefined
+      ? pendingKey(input.orgId, name)
+      : attachmentKey(input.orgId, input.target, name);
+  const scanner = uploadScanner();
+  if (input.target !== undefined && scanner !== undefined) {
+    throw targetUnscanned(caller, key, scanner.name);
+  }
 
   if (!policy.allowedContentTypes.includes(declared)) {
     throw contentTypeNotAllowed(key, declared, policy.allowedContentTypes);

package/src/image-variant.ts

@@ -0,0 +1,106 @@
+// Single responsibility: `variant()` — one resized image, made by the app's image driver and kept on
+// the disk under `variantKey(…, { revision })`, so the second ask is a `stat` and never a decode.
+// The driver is an ARGUMENT, structurally `@ultimat3/seo`'s `ImageTransformDriver`: storage is tier
+// 1 beside seo and imports none of it; the `images` port value is what an app passes.
+
+import { assert, finiteCount, IMAGE_MIME_TYPES } from '@ultimat3/core';
+import type { StorageDriver, StorageObject } from './driver';
+import { objectNotFound } from './errors';
+import {
+  driverEncodingMismatch,
+  notARaster,
+  variantFormatUnknown,
+  variantSourceChanged,
+} from './errors-variant';
+import { type VariantFormat, variantFormatOf, variantKey, variantRevision } from './image';
+import { normalizeContentType } from './upload';
+
+/** `@ultimat3/seo`'s `TransformRequest`, field for field: `src` is the SOURCE storage key. */
+export interface VariantRequest {
+  src: string;
+  width: number;
+  format?: string;
+  quality?: number;
+}
+
+/** `@ultimat3/seo`'s `TransformedImage`, field for field. */
+export interface VariantBytes {
+  bytes: Uint8Array;
+  contentType: string;
+  width: number;
+  height: number;
+}
+
+/**
+ * The half of `ImageTransformDriver` this needs — so `runtime.ts`'s `images` driver, a
+ * `builtinImageDriver({ read: (src) => disk.get(src).then((r) => r.bytes) })` or a CDN's, is passed
+ * as it is. Its `read` must resolve `src` against the SAME disk handed to `variant()`.
+ */
+export interface VariantTransformer {
+  readonly name: string;
+  transform(request: VariantRequest): Promise<VariantBytes>;
+}
+
+export interface VariantOptions {
+  readonly disk: StorageDriver;
+  readonly images: VariantTransformer;
+  /** Whole pixels, at least one. A width above the source's is the driver's to clamp. */
+  readonly width: number;
+  /** Omitted: the source's own encoding (png, jpeg, webp); a gif or avif source must name one. */
+  readonly format?: VariantFormat | undefined;
+}
+
+export interface StoredVariant {
+  readonly key: string;
+  readonly object: StorageObject;
+  /** True when THIS call transformed and wrote it; false when it was already on the disk. */
+  readonly created: boolean;
+}
+
+/** What a driver can resample: every raster core can probe. An svg has no pixels to resize. */
+const RASTER_TYPES: ReadonlySet<string> = new Set(
+  Object.entries(IMAGE_MIME_TYPES)
+    .filter(([format]) => format !== 'svg')
+    .map(([, type]) => type),
+);
+
+/**
+ * The variant of `key` at `width` (and `format`), from the disk if it is there, else transformed by
+ * `images` and written. Idempotent: the key is derived from the source's revision, so a repeat is a
+ * hit and an overwritten source is a different key. Concurrent first calls both write the same key
+ * with the same bytes — harmless, and cheaper than a lock.
+ */
+export async function variant(key: string, options: VariantOptions): Promise<StoredVariant> {
+  const width = finiteCount('variant', 'width', options.width, 1);
+  const { disk, images } = options;
+  const source = await disk.stat(key);
+  if (source === undefined) throw objectNotFound(disk.name, key);
+  const sourceType = normalizeContentType(source.contentType);
+  if (!RASTER_TYPES.has(sourceType)) throw notARaster(key, sourceType);
+  const format = options.format === undefined ? variantFormatOf(sourceType) : options.format;
+  if (format === undefined) throw variantFormatUnknown(key, sourceType);
+  const revision = variantRevision(source.etag);
+  assert(
+    revision !== undefined,
+    `variant('${key}'): the source etag "${source.etag}" carries no 8-hex revision, so its variant has no key that an overwrite would miss`,
+    `x doctor --json   # the disk driver answers no content etag; serve ${key} through /media/* instead, which transforms without storing`,
+  );
+  const target = variantKey(key, { width, format, revision });
+
+  const stored = await disk.stat(target);
+  if (stored !== undefined) return { key: target, object: stored, created: false };
+
+  const made = await images.transform({ src: key, width, format });
+  const expected = IMAGE_MIME_TYPES[format];
+  if (normalizeContentType(made.contentType) !== expected) {
+    throw driverEncodingMismatch(key, images.name, expected, made.contentType);
+  }
+  // The driver read the source itself: bracketing it with two stats is how these bytes are known to
+  // be the revision the key names, and not an overwrite that landed while it read.
+  const after = await disk.stat(key);
+  if (after?.etag !== source.etag) {
+    throw variantSourceChanged(key, source.etag, after?.etag ?? 'deleted');
+  }
+  const object = await disk.put(target, made.bytes, { contentType: expected });
+  return { key: target, object, created: true };
+}

package/src/index.ts

@@ -5,11 +5,12 @@ export type { AcceptSignedUploadInput, SignedRequestInput } from './accept';
 export { acceptSignedUpload, readSignedObject, signedUploadConstraints } from './accept';
 export type { AcceptSignedPartInput } from './accept-part';
 export { acceptSignedPart } from './accept-part';
+export type { AcceptSignedUploadStreamInput } from './accept-stream';
+export { acceptSignedUploadStream } from './accept-stream';
 export type {
   AttachmentTarget,
   DeleteVariantsInput,
   PromoteAttachmentInput,
-  ReleaseQuarantineInput,
   SweepFailure,
   SweepOrphansInput,
   SweepResult,
@@ -19,17 +20,10 @@ export {
   attachmentPrefix,
   deleteVariants,
   isPendingKey,
-  isQuarantinedKey,
   PENDING_SEGMENT,
   pendingKey,
-  pendingPrefix,
   promoteAttachment,
-  QUARANTINE_SEGMENT,
-  quarantineKey,
-  quarantinePrefix,
-  releaseQuarantine,
   sweepOrphans,
-  uploadExtension,
   uploadName,
 } from './attachment';
 export type { PumpLimit } from './byte-pump';
@@ -47,13 +41,13 @@ export type {
   StorageListEntry,
   StorageObject,
   StorageRead,
+  StreamOptions,
 } from './driver';
 export {
   // Exported for the same reason `toBytes` is: a driver written outside this package has to
   // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
   assertPutOptions,
   DEFAULT_CONTENT_TYPE,
-  DEFAULT_LIST_LIMIT,
   etagOf,
   resolveListLimit,
   sha256Base64,
@@ -77,36 +71,21 @@ export type { S3FetchLike } from './driver-s3-signed';
 export type { StorageErrorCode, StorageErrorInit } from './errors';
 export {
   checksumMismatch,
-  contentTypeMismatch,
-  contentTypeNotAllowed,
-  contentTypeUnrecognised,
   deleteFailed,
-  diskUnknown,
   getTooLarge,
   isStorageError,
   keyConflict,
   keyUnshared,
-  listFailed,
   objectNotFound,
   orgMismatch,
-  pathUnsafe,
   putFailed,
-  putTooLarge,
   readFailed,
-  STORAGE_ERROR_CODES,
-  STORAGE_ERROR_TITLES,
   StorageError,
-  signedUrlExpired,
-  signedUrlRejected,
-  signedUrlUnverifiable,
-  signingSecretMissing,
   tooLarge,
-  uploadFailed,
   xmlBodyUnreadable,
 } from './errors';
-export { multipartUnsupported, partsInvalid, uploadUnknown } from './errors-multipart';
-export { alreadyPromoted, quarantined } from './errors-promote';
-export { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+export { alreadyPromoted } from './errors-promote';
+export { rangeTooLarge } from './errors-range';
 export type {
   AbortResult,
   AbortStaleUploadsInput,
@@ -156,6 +135,14 @@ export {
   variantRevision,
   variantSourceOf,
 } from './image';
+export type {
+  StoredVariant,
+  VariantBytes,
+  VariantOptions,
+  VariantRequest,
+  VariantTransformer,
+} from './image-variant';
+export { variant } from './image-variant';
 export type { WarmFailure, WarmVariantsInput, WarmVariantsResult } from './image-warm';
 export { warmVariants } from './image-warm';
 export type {
@@ -165,7 +152,7 @@ export type {
   SignPartOptions,
   UploadedPart,
 } from './multipart';
-export { MAX_PART_BYTES, MAX_PARTS, MIN_PART_BYTES, matchParts, partBytesFor } from './multipart';
+export { MAX_PARTS, MIN_PART_BYTES, partBytesFor } from './multipart';
 export type {
   LockedAction,
   ObjectLock,
@@ -173,19 +160,17 @@ export type {
   ObjectRetention,
   RetentionMode,
 } from './object-lock';
-export { isLocked, ObjectLockedError, RETENTION_MODES } from './object-lock';
+export { isLocked, ObjectLockedError } from './object-lock';
 export {
   assertSafeKey,
   isSafeKey,
   isTenantScoped,
   isWithinOrg,
   joinKey,
-  keyDirname,
   keyExtname,
   MAX_KEY_LENGTH,
   META_DIR,
   ORG_PREFIX,
-  orgPrefix,
   scopedKey,
 } from './path';
 export type { PutStreamOptions } from './put-stream';
@@ -195,7 +180,8 @@ export { assertPutStream, streamLimit } from './put-stream';
  * fourth answer to what a range means.
  */
 export type { ByteRange, GetOptions } from './range';
-export { assertGetOptions, assertStreamRange, servedRange, streamedRange } from './range';
+export { assertStreamRange, streamedRange } from './range';
+export type { RequestCeiling } from './request-ceiling';
 export type {
   SignedPart,
   SignedUrlConstraints,
@@ -208,10 +194,7 @@ export {
   buildSignedUrl,
   canonicalRequest,
   DEFAULT_SIGNED_URL_BASE,
-  DEFAULT_SIGNED_URL_TTL_MS,
   SIGNED_URL_FAILURES,
-  SIGNED_URL_PARAMS,
-  SIGNED_URL_VERSION,
   signConstraints,
   signedUrlBaseFor,
   signedUrlBasePath,
@@ -229,8 +212,9 @@ export type {
   StorageSubjectTarget,
   StorageSubjectTargetOptions,
 } from './subject-target';
-export { STORAGE_SUBJECT_COLUMNS, storageSubjectTarget } from './subject-target';
+export { storageSubjectTarget } from './subject-target';
 export type {
+  ScanUnavailablePolicy,
   StoredHeadCandidate,
   UploadCandidate,
   UploadPolicy,
@@ -239,14 +223,12 @@ export type {
   ValidatedUpload,
 } from './upload';
 export {
-  contentTypeMatches,
   DEFAULT_MAX_UPLOAD_BYTES,
   DOCUMENT_CONTENT_TYPES,
   IMAGE_CONTENT_TYPES,
   MAX_LEADING_WHITESPACE,
   normalizeContentType,
   SNIFF_WINDOW_BYTES,
-  sniffContentType,
   uploadPolicy,
   validateStoredHead,
   validateUpload,
@@ -260,18 +242,17 @@ export type {
   UploadSource,
 } from './upload-client';
 export {
-  defaultSignedPut,
   fetchSignedPut,
   uploadFile,
   xhrSignedPut,
 } from './upload-client';
 export type {
   MultipartUploadClient,
-  MultipartUploadInput,
   UploadSessionRef,
 } from './upload-client-multipart';
 export {
   DEFAULT_PART_THRESHOLD_BYTES,
   PART_CONCURRENCY,
-  uploadInParts,
 } from './upload-client-multipart';
+// The `uploadScanner` port's reference: the interface and its installer are on `./adapter`.
+export { EICAR_TEST_STRING, memoryUploadScanner } from './upload-scanner-memory';

package/src/path.ts

@@ -3,7 +3,8 @@
 // and an S3 disk into a cross-tenant read. Rejection is total: no sanitising, no rewriting —
 // a key that needed fixing was built wrong, and silently fixing it hides the bug.
 
-import { pathUnsafe } from './errors';
+import { renderFixLiteral } from '@ultimat3/core';
+import { pathUnsafe, StorageError } from './errors';
 
 /**
  * S3's own limit; keeping local and remote disks interchangeable requires the same ceiling.
@@ -32,6 +33,12 @@ export const META_DIR = '.meta';
 // `%2e%2e%2f` decodes to `../` in any layer that decodes twice (proxy, then framework).
 const ENCODED_SEPARATOR = /%(?:2e|2f|5c|00)/i;
 
+/**
+ * A Win32 device name, with or without an extension and in any case: `nul.txt` opens the device,
+ * never a file, on a local disk under Windows. Refused on every driver, so a key is one rule.
+ */
+const DEVICE_NAME = /^(?:con|prn|aux|nul|conin\$|conout\$|com[0-9¹²³]|lpt[0-9¹²³])\s*(?:\..*)?$/i;
+
 /** NUL and friends: a C-string API downstream truncates at the NUL and opens a different file. */
 function hasControlByte(key: string): boolean {
   for (let index = 0; index < key.length; index += 1) {
@@ -67,6 +74,10 @@ function unsafeReason(key: string): string | undefined {
     if (segment.length === 0) return 'contains an empty segment ("//" or a trailing "/")';
     if (segment === '.' || segment === '..') return `contains a "${segment}" segment`;
     if (segment !== segment.trim()) return `has a padded segment ${JSON.stringify(segment)}`;
+    // Win32 drops a trailing dot: `.meta.` IS the reserved sidecar dir, `a.` IS `a`.
+    if (segment.endsWith('.')) return `has a segment ending in "." ${JSON.stringify(segment)}`;
+    if (DEVICE_NAME.test(segment))
+      return `has a Windows device-name segment ${JSON.stringify(segment)}`;
   }
   return undefined;
 }
@@ -75,6 +86,21 @@ export function isSafeKey(key: string): boolean {
   return unsafeReason(key) === undefined;
 }
 
+/**
+ * The local disk's one extra rule, on Windows only: `a:b` is the NTFS stream `b` of the file `a`, so
+ * two keys would share one file's bytes. Everywhere else — s3, Linux, macOS — a `:` is an ordinary
+ * key byte, and ISO timestamps carry three, so the shared rule above admits it.
+ */
+export function assertLocalKey(key: string, platform: string = process.platform): string {
+  if (platform !== 'win32' || !key.includes(':')) return key;
+  throw new StorageError({
+    code: 'X_STORAGE_PATH_UNSAFE',
+    cause: `key ${JSON.stringify(key)} contains a ":", which a local disk on Windows stores as an NTFS alternate data stream of another file`,
+    fix: `await disk.put(${renderFixLiteral(key.replaceAll(':', '-'), "'<key>'")}, body)   # the same key with each ":" as "-" (2026-11-09T12-00-00Z for a timestamp)`,
+    meta: { key, reason: 'contains a ":" on win32' },
+  });
+}
+
 /** Returns the key unchanged, so it composes: `Bun.file(join(root, assertSafeKey(key)))`. */
 export function assertSafeKey(key: string): string {
   const reason = unsafeReason(key);

package/src/request-ceiling.ts

@@ -0,0 +1,45 @@
+// Single responsibility: the request ceiling of a disk whose signed PUT lands on THIS process (local,
+// memory). One request cannot carry more than the server reads in one, so a single-request grant
+// past it is refused when it is signed — the fix names the multipart grant, whose parts each fit.
+
+import { finiteCount } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+/** A number, or a reader of one: a host whose ceiling is declared after the disk is built. */
+export type RequestCeiling = number | (() => number);
+
+/**
+ * Screened where it is declared, as every byte ceiling is; a reader is screened each time it is
+ * read, at signing. The answer is `undefined` for "no ceiling declared".
+ */
+export const screenRequestCeiling = (
+  driver: string,
+  value: RequestCeiling | undefined,
+): (() => number | undefined) => {
+  const screen = (bytes: number): number =>
+    finiteCount(`the ${driver} disk driver`, 'maxRequestBytes', bytes, 1);
+  if (value === undefined) return () => undefined;
+  if (typeof value === 'function') return () => screen(value());
+  const fixed = screen(value);
+  return () => fixed;
+};
+
+/** A single-request PUT URL bound past what one request may carry. A part URL is never refused. */
+export function assertWithinRequestCeiling(
+  driver: string,
+  ceiling: number | undefined,
+  url: {
+    readonly method?: string | undefined;
+    readonly part?: unknown;
+    readonly bound: number | undefined;
+  },
+): void {
+  if (ceiling === undefined || url.part !== undefined || url.method !== 'PUT') return;
+  if (url.bound === undefined || url.bound <= ceiling) return;
+  throw new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `a single signed PUT of up to ${url.bound}B on the ${driver} disk is one request to this server, whose ceiling is ${ceiling}B (http.maxRequestBodyBytes)`,
+    fix: 'await grantMultipart({ disk, orgId, request, policy })   # parts, each one request under the ceiling — then signPart and completeUpload',
+    meta: { driver, bytes: url.bound, maxBytes: ceiling },
+  });
+}

package/src/storage-instrument.ts

@@ -0,0 +1,108 @@
+// Single responsibility: the disk an app resolves through `defineStorage`, reporting each call on
+// core's instrumentation bus as `storage.<verb>` inside a client span. One wrapper over the
+// `StorageDriver` contract, so every driver — shipped or third-party — is instrumented the same.
+
+import type { StorageEvent } from '@ultimat3/core';
+import { instrument, subscribed, withSpan } from '@ultimat3/core';
+import type { StorageDriver } from './driver';
+
+type StorageVerb = 'put' | 'get' | 'stat' | 'copy' | 'delete' | 'list';
+
+/** Which event each instrumented method reports as: a streamed write is a put, a stream a get. */
+const VERB_OF: Readonly<Record<string, StorageVerb>> = Object.freeze({
+  put: 'put',
+  putStream: 'put',
+  get: 'get',
+  stream: 'get',
+  streamRange: 'get',
+  stat: 'stat',
+  copy: 'copy',
+  delete: 'delete',
+  list: 'list',
+});
+
+/** The key a call is ABOUT: the destination of a copy, the prefix of a listing. */
+function keyOf(method: string, args: readonly unknown[]): string {
+  if (method === 'copy') return typeof args[1] === 'string' ? args[1] : '';
+  if (method === 'list') {
+    const options = args[0];
+    const prefix =
+      typeof options === 'object' && options !== null && 'prefix' in options
+        ? options.prefix
+        : undefined;
+    return typeof prefix === 'string' ? prefix : '';
+  }
+  return typeof args[0] === 'string' ? args[0] : '';
+}
+
+/** A size the answer states — `StorageObject.size`, or a `get()`'s object — never a guess. */
+function bytesOf(answer: unknown): number | undefined {
+  if (typeof answer !== 'object' || answer === null) return undefined;
+  const holder = 'object' in answer ? answer.object : answer;
+  if (typeof holder !== 'object' || holder === null || !('size' in holder)) return undefined;
+  return typeof holder.size === 'number' ? holder.size : undefined;
+}
+
+function report(name: `storage.${StorageVerb}`, event: StorageEvent): void {
+  if (subscribed(name)) instrument(name, event);
+}
+
+/**
+ * The driver, every contract method wrapped and every other member (a test disk's `objects()`,
+ * `multipart`, `registerAs`) passed through bound to the driver. The driver's calls to its OWN
+ * methods stay unwrapped: one caller's call is one event.
+ */
+export function instrumentedDisk(disk: string, driver: StorageDriver): StorageDriver {
+  const wrapped = new Map<PropertyKey, unknown>();
+  return new Proxy(driver, {
+    get(target, property) {
+      const known = wrapped.get(property);
+      if (known !== undefined) return known;
+      const value: unknown = Reflect.get(target, property, target);
+      if (typeof value !== 'function') return value;
+      // A Proxy `get` is handed every name, `constructor` included: an own key or no verb.
+      const verb =
+        typeof property === 'string' && Object.hasOwn(VERB_OF, property)
+          ? VERB_OF[property]
+          : undefined;
+      const method = value as (...args: unknown[]) => unknown;
+      const bound =
+        verb === undefined
+          ? method.bind(target)
+          : (...args: unknown[]): Promise<unknown> =>
+              call(disk, verb, keyOf(property as string, args), driver.name, () =>
+                Promise.resolve(method.apply(target, args)),
+              );
+      wrapped.set(property, bound);
+      return bound;
+    },
+  });
+}
+
+async function call(
+  disk: string,
+  verb: StorageVerb,
+  key: string,
+  driverName: string,
+  work: () => Promise<unknown>,
+): Promise<unknown> {
+  const name = `storage.${verb}` as const;
+  const started = performance.now();
+  try {
+    const answer = await withSpan(name, work, {
+      kind: 'client',
+      attributes: { 'ultimate.storage.disk': disk, 'ultimate.storage.driver': driverName },
+    });
+    const bytes = bytesOf(answer);
+    report(name, {
+      disk,
+      key,
+      ...(bytes === undefined ? {} : { bytes }),
+      durationMs: performance.now() - started,
+    });
+    return answer;
+  } catch (error) {
+    report(name, { disk, key, durationMs: performance.now() - started, error });
+    throw error;
+  }
+}

package/src/storage.ts

@@ -8,6 +8,7 @@ import { ConfigInvalidError } from '@ultimat3/core';
 import type { StorageDriver } from './driver';
 import { diskUnknown } from './errors';
 import { isSafeKey, isTenantScoped } from './path';
+import { instrumentedDisk } from './storage-instrument';
 
 export interface StorageConfig {
   readonly disks: Readonly<Record<string, StorageDriver>>;
@@ -96,12 +97,12 @@ export function defineStorage(config: StorageConfig): Storage {
   // `.put()` was a bare `TypeError` inside app code — `diskUnknown` unreachable for `constructor`,
   // `toString`, `valueOf`, `hasOwnProperty` and `__proto__`. One function was already answering
   // one question two ways: `default: 'constructor'` is refused above, off `Object.keys`.
-  const disks = new Map(Object.entries(config.disks));
+  const declared = new Map(Object.entries(config.disks));
   // One driver instance, one disk name. A driver told two names keeps the last, and every URL it
   // minted under the first then resolves to a disk it is not — refused here rather than 404ing
   // one alias at a time. Two disks over one root are two `localDriver()` calls.
   const registered = new Map<StorageDriver, string>();
-  for (const [diskName, driver] of disks) {
+  for (const [diskName, driver] of declared) {
     const already = registered.get(driver);
     if (already !== undefined) {
       throw new ConfigInvalidError({
@@ -112,6 +113,11 @@ export function defineStorage(config: StorageConfig): Storage {
     registered.set(driver, diskName);
     driver.registerAs?.(diskName);
   }
+  // What `disk()` hands out: the declared driver, reporting each call on the bus (`storage.<verb>`).
+  // Built once per disk, so a disk is the same object on every resolution.
+  const disks = new Map(
+    [...declared].map(([diskName, driver]) => [diskName, instrumentedDisk(diskName, driver)]),
+  );
   const shared = sharedPrefixes(config.shared, names);
   const storageInstance: Storage = {
     defaultDisk,