@ultimat3/storage 22.15.0 → 24.0.0

package/src/driver-local-write.ts

@@ -0,0 +1,185 @@
+// Single responsibility: how the local disk WRITES one object — the bytes, the sidecar and a
+// pending marker, staged under `.meta/.tmp/` and renamed into place in the one order whose every
+// crash point reads as absent, whole or untyped; refused by code when the disk says no.
+
+// why: Bun has no `rename` and no `mkdir` — `Bun.write` creates parents and replaces in place,
+// which is exactly the non-atomic write this file exists to stop. Delete both the day Bun ships them.
+import { mkdir, rename } from 'node:fs/promises';
+import { renderFixShellArg, stringField } from '@ultimat3/core';
+import type { Sidecar } from './driver-local-sidecar';
+import { isStorageError, keyConflict, putFailed } from './errors';
+import { META_DIR } from './path';
+
+/** Inside `.meta/`, so the listing's one filter already keeps a staged file out of the keys. */
+const STAGING_DIR = `${META_DIR}/.tmp`;
+
+export const sidecarPathOf = (key: string): string => `${META_DIR}/${key}.json`;
+/** Beside the sidecar, and never one itself: a sidecar's name ends in `.json`. */
+export const pendingPathOf = (key: string): string => `${META_DIR}/${key}.json.pending`;
+
+const codeOf = (error: unknown): string | undefined => stringField(error, 'code');
+/** `mkdir -p` through a file, a rename onto a directory, a write under a file. */
+const isPathConflict = (error: unknown): boolean =>
+  ['ENOTDIR', 'EEXIST', 'EISDIR', 'ENOTEMPTY'].includes(codeOf(error) ?? '');
+const isAbsent = (error: unknown): boolean => ['ENOENT', 'ENOTDIR'].includes(codeOf(error) ?? '');
+
+/** The object KEY a path inside the root stands for — a sidecar's path names its object. */
+const keyAt = (relative: string): string =>
+  relative.startsWith(`${META_DIR}/`)
+    ? relative.slice(META_DIR.length + 1).replace(/\.json(\.pending)?$/, '')
+    : relative;
+
+/** The first ancestor of `relative` that is a FILE: the stored object standing where a directory must be. */
+async function fileInTheWay(root: string, relative: string): Promise<string | undefined> {
+  const segments = relative.split('/').slice(0, -1);
+  for (let depth = 1; depth <= segments.length; depth += 1) {
+    const ancestor = segments.slice(0, depth).join('/');
+    if (await Bun.file(`${root}/${ancestor}`).exists()) return keyAt(ancestor);
+  }
+  // Nothing INSIDE the root is in the way: the root itself is the problem, and that is the
+  // disk refusing the write, not two keys colliding.
+  return undefined;
+}
+
+/**
+ * Make `relative` writable as a FILE, or refuse. Runs for both of an object's paths BEFORE either
+ * is touched: the sidecar tree collides where the object tree does not (`a` and `a.json/b`), and a
+ * put() that wrote its bytes and then failed on its sidecar left an object nobody had recorded.
+ */
+async function claim(write: ObjectWrite, relative: string): Promise<void> {
+  const { root, key } = write;
+  const target = `${root}/${relative}`;
+  try {
+    await mkdir(target.slice(0, target.lastIndexOf('/')), { recursive: true });
+  } catch (error) {
+    const blocking = isPathConflict(error) ? await fileInTheWay(root, relative) : undefined;
+    throw blocking === undefined ? error : keyConflict(write.disk, key, blocking);
+  }
+  let directory = false;
+  try {
+    directory = (await Bun.file(target).stat()).isDirectory();
+  } catch (error) {
+    if (!isAbsent(error)) throw error;
+  }
+  // The keys in the way live UNDER this path: `<key>/…`, or `<key>.json/…` in the sidecar tree.
+  const beneath = relative.startsWith(`${META_DIR}/`)
+    ? relative.slice(META_DIR.length + 1)
+    : relative;
+  if (directory) throw keyConflict(write.disk, key, `${beneath}/`);
+}
+
+const discard = async (path: string): Promise<void> => {
+  await Bun.file(path)
+    .delete()
+    .catch(() => undefined);
+};
+
+export interface ObjectWrite {
+  readonly root: string;
+  readonly key: string;
+  /** The name the disk was REGISTERED under — what a refusal's `disk('…')` call must name. */
+  readonly disk: string;
+  /** A `BunFile` is a `Blob`: a copy hands the source file over and no byte crosses the heap. */
+  readonly body: Uint8Array | Blob;
+  /** `etag` MUST be the body's own: it is what the pending marker announces. */
+  readonly sidecar: Sidecar;
+}
+
+/** The four mutations a commit makes, in order — the seam a crash test dies at. */
+export interface WriteSteps {
+  rename(from: string, to: string): Promise<void>;
+  unlink(path: string): Promise<void>;
+}
+
+const REAL_STEPS: WriteSteps = {
+  rename: (from, to) => rename(from, to),
+  unlink: async (path) => {
+    await Bun.file(path).delete();
+  },
+};
+
+/**
+ * Stage three files, then four steps: (1) rename the pending MARKER, which holds the new etag;
+ * (2) rename the sidecar; (3) rename the bytes; (4) remove the marker. Each rename replaces a
+ * directory entry whole, so no reader ever opens half a file.
+ *
+ * The order is chosen by what a crash leaves (`driver-local-crash.test.ts` dies at every step):
+ * - before (3), a FRESH key has no bytes file and so no object — absent, never half-present;
+ * - before (2), an overwrite still has the previous sidecar over the previous bytes — whole;
+ * - between (2) and (3), the new sidecar sits over the OLD bytes, and the marker naming that
+ *   sidecar's etag is what tells `headObject` not to believe it;
+ * - between (3) and (4) the pair is whole and still marked, so a read re-checks it and a listing
+ *   reports it untyped until the next put.
+ * Bytes-first has no such table: its torn overwrite is new bytes under the old type, undetectable.
+ */
+async function commit(write: ObjectWrite, steps: WriteSteps): Promise<void> {
+  const sidecarPath = sidecarPathOf(write.key);
+  const pendingPath = pendingPathOf(write.key);
+  await claim(write, write.key);
+  await claim(write, sidecarPath);
+  await claim(write, pendingPath);
+  const staged = `${write.root}/${STAGING_DIR}/${crypto.randomUUID()}`;
+  // A second writer can make the colliding key between `claim` and the rename; only a RENAME's
+  // refusal is that, never a failed staging write.
+  const settle = async (suffix: string, relative: string): Promise<void> => {
+    await steps.rename(`${staged}.${suffix}`, `${write.root}/${relative}`).catch((error) => {
+      throw isPathConflict(error) ? keyConflict(write.disk, write.key, write.key) : error;
+    });
+  };
+  try {
+    await Bun.write(`${staged}.object`, write.body);
+    await Bun.write(`${staged}.sidecar`, JSON.stringify(write.sidecar));
+    await Bun.write(`${staged}.pending`, write.sidecar.etag);
+    await settle('pending', pendingPath);
+    await settle('sidecar', sidecarPath);
+    await settle('object', write.key);
+  } catch (error) {
+    for (const suffix of ['object', 'sidecar', 'pending']) await discard(`${staged}.${suffix}`);
+    throw error;
+  }
+  // The object is COMMITTED: all three renames landed. A marker that will not clear is not a
+  // failed put — reporting one told the caller to retry a write every reader can already see.
+  // What it leaves is exactly the crash-at-step-4 state, which `headObject` re-checks.
+  await steps.unlink(`${write.root}/${pendingPath}`).catch(() => undefined);
+}
+
+/**
+ * The local write, coded. Whatever the filesystem refuses with — `EACCES`, `ENOSPC`, `EROFS`, a
+ * root that is a file — leaves here as `X_STORAGE_PUT_FAILED` carrying the errno, where it used to
+ * be the bare `Error` out of `Bun.write`. A refusal this package already named passes through.
+ */
+export async function commitObject(
+  write: ObjectWrite,
+  steps: WriteSteps = REAL_STEPS,
+): Promise<void> {
+  try {
+    await commit(write, steps);
+  } catch (error) {
+    if (isStorageError(error)) throw error;
+    const at = renderFixShellArg(write.root, '<the disk root>');
+    throw putFailed(write.disk, write.key, error, `ls -ld ${at} && df -h ${at}`);
+  }
+}
+
+/** Runs `task` after every earlier task queued under the same key has settled. */
+export type KeyedQueue = <T>(key: string, task: () => Promise<T>) => Promise<T>;
+
+/**
+ * One writer — or one reader — per key at a time, inside this process. An object is two files, so
+ * two unserialised `put()`s of one key interleaved their four writes and left one's bytes under the
+ * other's etag; a `get()` between a writer's two renames read the same mismatch.
+ */
+export function keyedQueue(): KeyedQueue {
+  const tails = new Map<string, Promise<unknown>>();
+  return async <T>(key: string, task: () => Promise<T>): Promise<T> => {
+    const result = (tails.get(key) ?? Promise.resolve()).then(task, task);
+    const tail = result.catch(() => undefined);
+    tails.set(key, tail);
+    try {
+      return await result;
+    } finally {
+      // Only the LAST task clears the entry, or a Map of every key ever written is a leak.
+      if (tails.get(key) === tail) tails.delete(key);
+    }
+  };
+}

package/src/driver-local.ts

@@ -1,18 +1,19 @@
 // Single responsibility: the dev-default disk — a real, working driver over `Bun.file` /
-// `Bun.write` rooted at one directory, so `x dev` needs no MinIO and no cloud account.
+// `Bun.write` rooted at one directory, so `x dev` needs no S3 server and no cloud account.
 // Content type, etag and user metadata live in a sidecar under `.meta/`: a POSIX file has
 // nowhere to keep them, and `get` must round-trip exactly what `put` was handed.
 
 import {
   type Clock,
   finiteCount,
-  isLocal,
+  NotImplementedError,
   type ResolveEnvironmentOptions,
-  resolveEnvironment,
   stringField,
   systemClock,
 } from '@ultimat3/core';
 import {
+  assertListOptions,
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   etagOf,
   type ListOptions,
@@ -28,52 +29,18 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
-import {
-  checksumMismatch,
-  deleteFailed,
-  listFailed,
-  objectNotFound,
-  signingSecretMissing,
-  storageNotImplemented,
-} from './errors';
+import { etagOfFile, headObject, readObjectBytes } from './driver-local-read';
+import type { Sidecar } from './driver-local-sidecar';
+import { commitObject, keyedQueue, pendingPathOf, sidecarPathOf } from './driver-local-write';
+import { checksumMismatch, deleteFailed, getTooLarge, listFailed, objectNotFound } from './errors';
 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,41 +71,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 } : {}),
-  };
+  /**
+   * 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;
 }
 
 /**
@@ -149,10 +86,11 @@ function parseSidecar(raw: unknown): Sidecar | undefined {
  */
 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". */
@@ -168,75 +106,34 @@ 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
   // stating where the route is mounted, and inference must not overwrite a decision.
   let baseUrl = options.baseUrl ?? signedUrlBaseFor(DRIVER_NAME);
-  // 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 HERE, 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.
-  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' }));
-  const secret = configured ?? DEV_SIGNING_SECRET;
+  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;
-    }
-  };
-
-  // 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 }),
-    };
-  };
+  // 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)));
 
   /** Removes one path, or reports WHY it could not — a swallowed refusal is a false erasure. */
   const removeIfPresent = async (path: string, key: string): Promise<void> => {
@@ -262,12 +159,14 @@ 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);
       const bytes = await toBytes(body, { driver: DRIVER_NAME, key: safe, maxBytes: maxPutBytes });
       const claimed = putOptions?.checksum;
       if (claimed !== undefined) {
@@ -280,8 +179,9 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
         cacheControl: putOptions?.cacheControl,
         metadata: putOptions?.metadata,
       };
-      await Bun.write(filePath(safe), bytes);
-      await Bun.write(metaPath(safe), JSON.stringify(sidecar));
+      await oneAtATime(safe, () =>
+        commitObject({ root, key: safe, disk: registered, body: bytes, sidecar }),
+      );
       return {
         key: safe,
         size: bytes.byteLength,
@@ -293,21 +193,29 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       };
     },
 
+    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(DRIVER_NAME, safe);
+        if (file.size > maxGetBytes) throw getTooLarge(DRIVER_NAME, safe, file.size, maxGetBytes);
+        const bytes = await readObjectBytes(root, safe);
+        // 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(DRIVER_NAME, safe);
+        return {
+          object: { ...entry, contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE },
+          bytes,
+        };
+      });
     },
 
     async stream(key: string): Promise<ReadableStream<Uint8Array>> {
@@ -321,19 +229,30 @@ 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);
+      // 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(DRIVER_NAME, source);
-      await Bun.write(filePath(destination), Bun.file(filePath(source)));
       const sidecar: Sidecar = {
         contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE,
         etag: entry.etag,
         cacheControl: entry.cacheControl,
         metadata: entry.metadata,
       };
-      await Bun.write(metaPath(destination), JSON.stringify(sidecar));
+      await oneAtATime(destination, () =>
+        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(DRIVER_NAME, source);
+        throw error;
+      });
       return {
         ...entry,
         key: destination,
@@ -347,8 +266,11 @@ 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 () => {
+        await removeIfPresent(filePath(safe), safe);
+        await removeIfPresent(metaPath(safe), safe);
+        await removeIfPresent(`${root}/${pendingPathOf(safe)}`, safe);
+      });
     },
 
     async exists(key: string): Promise<boolean> {
@@ -357,6 +279,7 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
 
     async list(listOptions?: ListOptions): Promise<ListPage> {
       const prefix = listOptions?.prefix ?? '';
+      assertListOptions(listOptions);
       const limit = resolveListLimit(listOptions?.limit);
       const cursor = listOptions?.cursor;
       const keys: string[] = [];