@ultimat3/storage 23.0.0 → 25.0.0

package/src/driver-local.ts

@@ -6,17 +6,20 @@
 import {
   type Clock,
   finiteCount,
-  isLocal,
+  NotImplementedError,
+  type Page,
+  pageOf,
   type ResolveEnvironmentOptions,
-  resolveEnvironment,
+  renderFixShellArg,
   stringField,
   systemClock,
 } from '@ultimat3/core';
 import {
+  assertListOptions,
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   etagOf,
   type ListOptions,
-  type ListPage,
   type PutOptions,
   resolveListLimit,
   type SignedUrlOptions,
@@ -28,52 +31,25 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
+import { etagOfFile, headObject, readObjectBytes, readSidecar } from './driver-local-read';
+import { lockOfSidecar, type Sidecar, sidecarLock } from './driver-local-sidecar';
+import { commitObject, keyedQueue, pendingPathOf, sidecarPathOf } from './driver-local-write';
+import { checksumMismatch, deleteFailed, getTooLarge, listFailed, objectNotFound } from './errors';
 import {
-  checksumMismatch,
-  deleteFailed,
-  listFailed,
-  objectNotFound,
-  signingSecretMissing,
-  storageNotImplemented,
-} from './errors';
+  assertObjectLockOptions,
+  isLocked,
+  type ObjectLock,
+  ObjectLockedError,
+  requestedLock,
+} from './object-lock';
 import { assertSafeKey, META_DIR } from './path';
 import type { SignedUrlVerification } from './signed-url';
 import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
+import { resolveSigningSecret } from './signing-secret';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 'local';
 
-/**
- * The dev-only fallback signing key. A literal, not a per-process random one, so a restart does
- * not invalidate every URL `x dev` handed out — and published in this repo, which is exactly why
- * `localDriver` refuses to use it outside a development or test environment.
- */
-export const DEV_SIGNING_SECRET = 'ultimate-dev-signing-secret';
-
-/** The env key production must set. Named once, read by the driver and by the predicate below. */
-export const STORAGE_SIGNING_SECRET_KEY = 'STORAGE_SIGNING_SECRET';
-
-/**
- * True while a local disk built without an explicit `signingSecret` would sign with the shipped
- * development key — `x doctor` reports it, exactly as it reports `usesDevCursorSecret()`.
- *
- * Reads the environment, not a driver instance: this is the same question `x doctor` asks about
- * the cursor secret, and a disk handed an explicit `signingSecret` in `app.config.ts` never
- * consults the variable at all.
- *
- * `env` is core's own slot, so this half of the guard reads the SAME table its other half does:
- * `dev-runtime.ts` asks `!isLocal({ env }) && usesDevStorageSecret({ env })`, and an embedding
- * caller (`serveApp({ env })`, a test fixture) whose `env` is not `process.env` used to get one
- * answer about the boot and one about the process — for the decision of whether a disk may be
- * signed with the published development key. Defaulted to `process.env`, so a bare call is
- * unchanged.
- */
-export function usesDevStorageSecret(options?: Pick<ResolveEnvironmentOptions, 'env'>): boolean {
-  const source = options?.env ?? (process.env as Record<string, string | undefined>);
-  const configured = source[STORAGE_SIGNING_SECRET_KEY];
-  return configured === undefined || configured === '' || configured === DEV_SIGNING_SECRET;
-}
-
 export interface LocalDriverOptions {
   /** Directory the disk owns outright. Created on first write. */
   readonly root: string;
@@ -104,72 +80,11 @@ export interface LocalDriverOptions {
    * discovers by being OOM-killed.
    */
   readonly maxPutBytes?: number | undefined;
-}
-
-interface Sidecar {
-  readonly contentType: string;
-  readonly etag: string;
-  readonly cacheControl?: string | undefined;
-  readonly metadata?: Readonly<Record<string, string>> | undefined;
-}
-
-// `!Array.isArray` is the load-bearing clause, matching `isPlainObject` in
-// `@ultimat3/schema`'s `builder.ts`: `typeof [] === 'object'` and every value of `['a','b']` is a
-// string, so an array in the `metadata` slot was handed back through `head()`/`get()` as object
-// metadata — against a `Record<string, string>` every reader downstream is typed on.
-const isStringRecord = (value: unknown): value is Readonly<Record<string, string>> =>
-  typeof value === 'object' &&
-  value !== null &&
-  !Array.isArray(value) &&
-  Object.values(value as Record<string, unknown>).every((entry) => typeof entry === 'string');
-
-function parseSidecar(raw: unknown): Sidecar | undefined {
-  if (typeof raw !== 'object' || raw === null) return undefined;
-  const record = raw as Record<string, unknown>;
-  const contentType = record['contentType'];
-  const etag = record['etag'];
-  if (typeof contentType !== 'string' || typeof etag !== 'string') return undefined;
-  // `put()` writes cacheControl/metadata into the same sidecar (below) — dropping them here
-  // silently truncated what was just written, even though `Sidecar` itself declares both.
-  const cacheControl = record['cacheControl'];
-  const metadata = record['metadata'];
-  return {
-    contentType,
-    etag,
-    ...(typeof cacheControl === 'string' ? { cacheControl } : {}),
-    ...(isStringRecord(metadata) ? { metadata } : {}),
-  };
-}
-
-/**
- * The secret a disk that mints its OWN URLs signs with — `localDriver` and `memoryDriver` both.
- *
- * A dev disk must work with zero config. Outside development the fallback is refused rather than
- * used: the literal is published, so signing with it hands every reader the power to mint a PUT
- * for any key with any size and type limit — which `acceptSignedUpload` then trusts over the app's
- * own `uploadPolicy`. Refused at construction, so the boot fails rather than the first upload.
- *
- * The published literal counts as no secret at all, whichever way it arrives: an env var or an
- * `app.config.ts` that pasted it in signs exactly as weakly as the fallback does. One table for
- * all three reads — the secret, the environment test and the environment the refusal names.
- * Splitting them is how the guard and the disk came to answer about two different processes.
- */
-export function resolveSigningSecret(
-  disk: string,
-  options: Pick<LocalDriverOptions, 'signingSecret' | 'env'>,
-): string {
-  const env = options.env ?? (process.env as Record<string, string | undefined>);
-  const supplied = options.signingSecret ?? env[STORAGE_SIGNING_SECRET_KEY];
-  const configured =
-    supplied === undefined || supplied === '' || supplied === DEV_SIGNING_SECRET
-      ? undefined
-      : supplied;
-  // FAILS CLOSED: a process that names no environment resolves as `production` here, the answer
-  // core's `assertNoDevSecretsOutsideLocal` gives. `isLocal`'s own fallback is `development`, so the
-  // process that forgot to say signed with the published key — exactly the one that must not.
-  if (configured === undefined && !isLocal({ env, fallback: 'production' }))
-    throw signingSecretMissing(resolveEnvironment({ env, fallback: 'production' }), disk);
-  return configured ?? DEV_SIGNING_SECRET;
+  /**
+   * Ceiling on ONE `get()`, because `get()` buffers the whole object too — and an object's size
+   * is the uploader's, not this process's. Defaults to `maxPutBytes`; past it, `stream()`.
+   */
+  readonly maxGetBytes?: number | undefined;
 }
 
 /**
@@ -180,15 +95,30 @@ export function resolveSigningSecret(
  */
 function refuseUnsupportedPut(putOptions?: PutOptions): void {
   if (putOptions?.serverSideEncryption === undefined) return;
-  throw storageNotImplemented(
-    'server-side encryption on the local driver (it writes plain files under one root)',
-    'drop serverSideEncryption from put(), and encrypt the disk itself — an s3Driver over a bucket with a default KMS rule, or a LUKS/FileVault volume under `root`',
-  );
+  throw new NotImplementedError({
+    cause:
+      'server-side encryption on the local driver (it writes plain files under one root) is not implemented by this driver — drop serverSideEncryption from put() and encrypt the disk itself: an s3Driver over a bucket with a default KMS rule, or a LUKS/FileVault volume under root',
+    fix: 'put(key, body)',
+  });
 }
 
 /** `ENOENT` is the one delete failure that means "already in the desired state". */
 const isMissingFile = (error: unknown): boolean => stringField(error, 'code') === 'ENOENT';
 
+/**
+ * A directory at an object's path is OTHER keys' parent (`c` beside `c/d`), never an object: no
+ * bytes are stored at the key, so deleting it is deleting an absent key. Asked only after an
+ * unlink failed, because the errno for "that is a directory" is `EISDIR` on Linux and `EPERM` on
+ * macOS — the stat is the portable answer.
+ */
+const isDirectory = async (path: string): Promise<boolean> =>
+  Bun.file(path)
+    .stat()
+    .then(
+      (stats) => stats.isDirectory(),
+      () => false,
+    );
+
 export function localDriver(options: LocalDriverOptions): StorageDriver {
   const root = options.root.replace(/\/+$/, '');
   // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicitly blanked key in a
@@ -199,7 +129,16 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     options.maxPutBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : options.maxPutBytes,
     1,
   );
+  const maxGetBytes = finiteCount(
+    'the local disk driver',
+    'maxGetBytes',
+    options.maxGetBytes === undefined ? maxPutBytes : options.maxGetBytes,
+    1,
+  );
   const clock = options.clock ?? systemClock;
+  const oneAtATime = keyedQueue();
+  // What `defineStorage` registered this driver as — the name a refusal's `disk('…')` must use.
+  let registered = DRIVER_NAME;
   // The segment is the disk's REGISTERED name, learned from `defineStorage` at boot — the driver
   // kind is not a mount point, and minting under it made every disk not literally named `local`
   // 404 its own URLs. An explicit `baseUrl` outranks the registration: that is the operator
@@ -208,44 +147,31 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
   const secret = resolveSigningSecret(DRIVER_NAME, options);
 
   const filePath = (key: string): string => `${root}/${key}`;
-  const metaPath = (key: string): string => `${root}/${META_DIR}/${key}.json`;
+  const metaPath = (key: string): string => `${root}/${sidecarPathOf(key)}`;
 
-  const readSidecar = async (key: string): Promise<Sidecar | undefined> => {
-    const file = Bun.file(metaPath(key));
-    if (!(await file.exists())) return undefined;
-    try {
-      const raw: unknown = await file.json();
-      return parseSidecar(raw);
-    } catch {
-      return undefined;
-    }
-  };
+  // Both QUEUED behind the key's writers, as `get()` is: unqueued, a measurement read the size of
+  // one generation before a commit and the sidecar of the next after it.
+  /** A listing's view: no bytes read, so a pair in doubt reports no type and no etag. */
+  const head = (key: string): Promise<StorageListEntry | undefined> =>
+    oneAtATime(key, () => headObject(root, key));
+  /** The same, settled against the bytes on disk — streamed through a hasher, never buffered. */
+  const measured = (key: string): Promise<StorageListEntry | undefined> =>
+    oneAtATime(key, () => headObject(root, key, () => etagOfFile(root, key, registered)));
 
-  // No `contentType` fallback: the sidecar is the only thing that knows, so a missing one means
-  // this driver does not know either — exactly what the s3 driver's `list()` reports. `get()`
-  // fills the default below, because a `StorageObject` promises a type and a read has one.
-  //
-  // `hash` is the ONLY thing that reads the object's bytes, and it defaults off. The etag used to
-  // be computed unconditionally when the sidecar was missing, under a comment saying "`list()`
-  // must not read every file it lists" — which is exactly what `list()` then did, one whole
-  // object at a time, sequentially, for every sidecar-less key on the disk (a `put()` that died
-  // between its two writes leaves one). `copy()` inherited it too, so a copy documented as never
-  // routing bytes through the heap buffered the whole source. A listing that cannot know an etag
-  // reports `''`, which is what the s3 listing already answers for a provider that returns none.
-  const head = async (key: string, hash = false): Promise<StorageListEntry | undefined> => {
-    const file = Bun.file(filePath(key));
-    if (!(await file.exists())) return undefined;
-    const sidecar = await readSidecar(key);
-    const etag = sidecar?.etag ?? (hash ? etagOf(new Uint8Array(await file.arrayBuffer())) : '');
-    return {
-      key,
-      size: file.size,
-      etag,
-      lastModified: new Date(file.lastModified),
-      ...(sidecar?.contentType === undefined ? {} : { contentType: sidecar.contentType }),
-      ...(sidecar?.cacheControl === undefined ? {} : { cacheControl: sidecar.cacheControl }),
-      ...(sidecar?.metadata === undefined ? {} : { metadata: sidecar.metadata }),
-    };
+  /**
+   * The lock the sidecar RECORDS, read whole even when the pair is in doubt: a torn write never
+   * unlocks an object. `undefined` when nothing on disk locks it now.
+   */
+  const lockAt = async (key: string): Promise<ObjectLock | undefined> => {
+    const lock = lockOfSidecar(await readSidecar(root, key));
+    return isLocked(lock, clock.now()) ? lock : undefined;
+  };
+  /** Called INSIDE the key's queue, so no writer of this process lands between check and commit. */
+  const refuseOverwrite = async (key: string, action: 'overwrite' | 'copy onto'): Promise<void> => {
+    const lock = await lockAt(key);
+    if (lock !== undefined) {
+      throw new ObjectLockedError({ disk: registered, key, action, lock, sidecar: metaPath(key) });
+    }
   };
 
   /** Removes one path, or reports WHY it could not — a swallowed refusal is a false erasure. */
@@ -253,12 +179,13 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     try {
       await Bun.file(path).delete();
     } catch (error) {
-      if (isMissingFile(error)) return;
+      if (isMissingFile(error) || (await isDirectory(path))) return;
       throw deleteFailed(
         DRIVER_NAME,
         key,
         error,
-        `make the disk root writable by this process, then retry: ls -ld ${root} && rm -f ${path}`,
+        // Screened: a key may carry `$(…)` and a root is configuration, and a fix: is pasted.
+        `make the disk root writable by this process, then retry: ls -ld ${renderFixShellArg(root, "'<the disk root>'")} && rm -f ${renderFixShellArg(path, "'<the object file>'")}`,
       );
     }
   };
@@ -272,58 +199,75 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     },
 
     registerAs(diskName: string): void {
+      registered = diskName;
       if (options.baseUrl === undefined) baseUrl = signedUrlBaseFor(diskName);
     },
 
     async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
       const safe = assertSafeKey(key);
       refuseUnsupportedPut(putOptions);
+      assertPutOptions(DRIVER_NAME, putOptions);
+      assertObjectLockOptions(DRIVER_NAME, putOptions, clock);
       const bytes = await toBytes(body, { driver: DRIVER_NAME, key: safe, maxBytes: maxPutBytes });
       const claimed = putOptions?.checksum;
       if (claimed !== undefined) {
         const actual = sha256Base64(bytes);
         if (claimed !== actual) throw checksumMismatch(safe, claimed, actual);
       }
+      const lastModified = clock.now();
       const sidecar: Sidecar = {
         contentType: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE,
         etag: etagOf(bytes),
         cacheControl: putOptions?.cacheControl,
         metadata: putOptions?.metadata,
+        // The write's instant, on the injected clock, recorded for every later read to report.
+        lastModified: lastModified.toISOString(),
+        ...sidecarLock(requestedLock(putOptions)),
       };
-      await Bun.write(filePath(safe), bytes);
-      await Bun.write(metaPath(safe), JSON.stringify(sidecar));
+      await oneAtATime(safe, async () => {
+        await refuseOverwrite(safe, 'overwrite');
+        await commitObject({ root, key: safe, disk: registered, body: bytes, sidecar });
+      });
       return {
         key: safe,
         size: bytes.byteLength,
         contentType: sidecar.contentType,
         etag: sidecar.etag,
-        lastModified: clock.now(),
+        lastModified,
         ...(sidecar.cacheControl === undefined ? {} : { cacheControl: sidecar.cacheControl }),
         ...(sidecar.metadata === undefined ? {} : { metadata: sidecar.metadata }),
       };
     },
 
+    async stat(key: string): Promise<StorageObject | undefined> {
+      const entry = await measured(assertSafeKey(key));
+      return entry && { ...entry, contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE };
+    },
+
     async get(key: string): Promise<StorageRead> {
       const safe = assertSafeKey(key);
-      const entry = await head(safe);
-      if (entry === undefined) throw objectNotFound(DRIVER_NAME, safe);
-      const bytes = new Uint8Array(await Bun.file(filePath(safe)).arrayBuffer());
-      return {
-        object: {
-          ...entry,
-          contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE,
-          // Hashed HERE and not inside `head`, so a sidecar-less object is read exactly once: a
-          // `get()` already holds every byte, and `head(key, true)` would have read them again.
-          etag: entry.etag === '' ? etagOf(bytes) : entry.etag,
-        },
-        bytes,
-      };
+      // Queued behind this key's writers: an object is two files, and a read between a put()'s
+      // renames is a pair in doubt this process has no need to meet.
+      return oneAtATime(safe, async () => {
+        const file = Bun.file(filePath(safe));
+        if (!(await file.exists())) throw objectNotFound(registered, safe);
+        if (file.size > maxGetBytes) throw getTooLarge(DRIVER_NAME, safe, file.size, maxGetBytes);
+        const bytes = await readObjectBytes(root, safe, registered);
+        // Settled against the bytes this read ALREADY holds: hashed only for a sidecar-less object
+        // or a pair in doubt, and then exactly once.
+        const entry = await headObject(root, safe, () => etagOf(bytes));
+        if (entry === undefined) throw objectNotFound(registered, safe);
+        return {
+          object: { ...entry, contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE },
+          bytes,
+        };
+      });
     },
 
     async stream(key: string): Promise<ReadableStream<Uint8Array>> {
       const safe = assertSafeKey(key);
       const file = Bun.file(filePath(safe));
-      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, safe);
+      if (!(await file.exists())) throw objectNotFound(registered, safe);
       return file.stream();
     },
 
@@ -331,24 +275,38 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     async copy(from: string, to: string): Promise<StorageObject> {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
-      // `hash: true` — the destination gets a sidecar, and a sidecar carrying `etag: ''` is a
-      // durable lie every later `get()` of the copy would trust. The read is bounded to the one
-      // case the source has no sidecar of its own; the common path still touches no bytes.
-      const entry = await head(source, true);
-      if (entry === undefined) throw objectNotFound(DRIVER_NAME, source);
-      await Bun.write(filePath(destination), Bun.file(filePath(source)));
+      // Measured, not merely read: the destination gets a sidecar, and one carrying `etag: ''` or
+      // a torn source's borrowed type is a durable lie every later `get()` of the copy would
+      // trust. The hash is streamed, and only for a sidecar-less source or a pair in doubt.
+      const entry = await measured(source);
+      if (entry === undefined) throw objectNotFound(registered, source);
+      const lastModified = clock.now();
       const sidecar: Sidecar = {
         contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE,
         etag: entry.etag,
         cacheControl: entry.cacheControl,
         metadata: entry.metadata,
+        lastModified: lastModified.toISOString(),
       };
-      await Bun.write(metaPath(destination), JSON.stringify(sidecar));
+      await oneAtATime(destination, async () => {
+        await refuseOverwrite(destination, 'copy onto');
+        await commitObject({
+          root,
+          key: destination,
+          disk: registered,
+          body: Bun.file(filePath(source)),
+          sidecar,
+        });
+      }).catch(async (error: unknown) => {
+        // The source was deleted while this copy waited its turn on the destination.
+        if (!(await Bun.file(filePath(source)).exists())) throw objectNotFound(registered, source);
+        throw error;
+      });
       return {
         ...entry,
         key: destination,
         contentType: sidecar.contentType,
-        lastModified: clock.now(),
+        lastModified,
       };
     },
 
@@ -357,18 +315,41 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       // Idempotent by contract: a missing key is already in the desired state. A REFUSED unlink
       // is not — a read-only mount or a root this process cannot write reports the bytes gone
       // when they are still on disk, which is the one lie an erasure sweep must never repeat.
-      await removeIfPresent(filePath(safe), safe);
-      await removeIfPresent(metaPath(safe), safe);
+      await oneAtATime(safe, async () => {
+        const lock = await lockAt(safe);
+        if (lock !== undefined) {
+          throw new ObjectLockedError({
+            disk: registered,
+            key: safe,
+            action: 'delete',
+            lock,
+            sidecar: metaPath(safe),
+          });
+        }
+        await removeIfPresent(filePath(safe), safe);
+        await removeIfPresent(metaPath(safe), safe);
+        await removeIfPresent(`${root}/${pendingPathOf(safe)}`, safe);
+      });
     },
 
     async exists(key: string): Promise<boolean> {
       return Bun.file(filePath(assertSafeKey(key))).exists();
     },
 
-    async list(listOptions?: ListOptions): Promise<ListPage> {
+    /** From the sidecar, as recorded — a lapsed retention is still reported, as S3 reports it. */
+    async retentionOf(key: string): Promise<ObjectLock> {
+      const safe = assertSafeKey(key);
+      return oneAtATime(safe, async () => {
+        if (!(await Bun.file(filePath(safe)).exists())) throw objectNotFound(registered, safe);
+        return lockOfSidecar(await readSidecar(root, safe));
+      });
+    },
+
+    async list(listOptions?: ListOptions): Promise<Page<StorageListEntry>> {
       const prefix = listOptions?.prefix ?? '';
+      assertListOptions(listOptions);
       const limit = resolveListLimit(listOptions?.limit);
-      const cursor = listOptions?.cursor;
+      const cursor = listOptions?.cursor ?? undefined;
       const keys: string[] = [];
       try {
         // `dot: true`, and it is load-bearing: without it a glob matches no dot-prefixed entry, so
@@ -395,7 +376,7 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
         }
       } catch (error) {
         // A disk nobody has written to yet has no directory: an empty listing, not an error.
-        if (isMissingFile(error)) return { objects: [], truncated: false };
+        if (isMissingFile(error)) return pageOf([], null);
         // Everything else is a refusal, and a bare `catch` reported all of them as "this disk is
         // empty" — `EACCES` on the root, `ENOTDIR` on a root that is a file, an I/O error on the
         // mount. `sweepOrphans` walks `list()`, so that swallow certified an unreadable prefix as
@@ -405,7 +386,7 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
           DRIVER_NAME,
           prefix,
           error,
-          `make the disk root readable by this process, then retry: ls -ld ${root}`,
+          `make the disk root readable by this process, then retry: ls -ld ${renderFixShellArg(root, "'<the disk root>'")}`,
         );
       }
       keys.sort();
@@ -415,14 +396,11 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
         const object = await head(key);
         if (object !== undefined) objects.push(object);
       }
-      const truncated = keys.length > page.length;
-      // `limit` is a positive integer, so a truncated page always HAS a last key: the guard is the
-      // type's and not a second condition. It used to be one, and `limit: 0` fell through it —
-      // an empty page reported as complete over a disk that was not.
-      const last = page.at(-1);
-      return truncated && last !== undefined
-        ? { objects, truncated, cursor: last }
-        : { objects, truncated: false };
+      // The cursor is minted only when a key PAST the page exists — `keys` is every match, so a
+      // full last page answers no cursor. `limit` is a positive integer, so a page with more after
+      // it always HAS a last key: the `?? null` is the type's, not a second condition. It used to
+      // be one, and `limit: 0` fell through it — an empty page reported as complete.
+      return pageOf(objects, keys.length > page.length ? (page.at(-1) ?? null) : null);
     },
 
     async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {

package/src/driver-memory-conflict.ts

@@ -0,0 +1,45 @@
+// Single responsibility: which stored key stands in the way of a new one, answered over a set of
+// keys exactly as `driver-local-write.ts`'s `claim()` answers it over a directory tree — so the
+// memory disk refuses the keys the local disk it stands in for cannot hold.
+
+import { pendingPathOf, sidecarPathOf } from './driver-local-write';
+import { META_DIR } from './path';
+
+/** `.meta/<key>.json` → `<key>.json`: the sidecar tree, read as keys. */
+const inSidecarTree = (relative: string): string => relative.slice(META_DIR.length + 1);
+
+/** Every proper ancestor directory of `path`, shallowest first: what `mkdir -p` would make. */
+const ancestorsOf = (path: string): readonly string[] => {
+  const segments = path.split('/').slice(0, -1);
+  return segments.map((_, depth) => segments.slice(0, depth + 1).join('/'));
+};
+
+/**
+ * The key in the way of storing `key`, spelled as the local disk's `X_STORAGE_KEY_CONFLICT` spells
+ * it (`blocking`), or `undefined`. Checked in `claim()`'s order — the object path, its sidecar,
+ * its pending marker — each first for a FILE where a directory must be, then for a DIRECTORY
+ * where the file must go. A marker is transient (cleared on commit), so it is never in the way of
+ * a later key; a directory where one must be written still is.
+ */
+export function keyInTheWay(stored: ReadonlyMap<string, unknown>, key: string): string | undefined {
+  // Object tree: `a` stored blocks `a/b`; `c/d` stored blocks `c` (reported as `c/`).
+  for (const ancestor of ancestorsOf(key)) if (stored.has(ancestor)) return ancestor;
+  const beneath = (prefix: string): boolean => {
+    for (const other of stored.keys()) if (other.startsWith(prefix)) return true;
+    return false;
+  };
+  if (beneath(`${key}/`)) return `${key}/`;
+  // Sidecar tree: `.meta/<k>.json` is a FILE per stored key `k`, and its directories are the
+  // object tree's — so `s` stored blocks `s.json/x`, and `t.json/x` stored blocks `t`.
+  const sidecar = inSidecarTree(sidecarPathOf(key));
+  for (const ancestor of ancestorsOf(sidecar)) {
+    if (ancestor.endsWith('.json') && stored.has(ancestor.slice(0, -'.json'.length))) {
+      return ancestor.slice(0, -'.json'.length);
+    }
+  }
+  if (beneath(`${sidecar}/`)) return `${sidecar}/`;
+  const pending = inSidecarTree(pendingPathOf(key));
+  // `<k>.json.pending/` is a directory exactly when a key's sidecar lives beneath it.
+  if (beneath(`${pending}/`)) return `${pending}/`;
+  return undefined;
+}