@ultimat3/storage 24.0.0 → 25.1.0

package/src/driver-local.ts

@@ -7,7 +7,10 @@ import {
   type Clock,
   finiteCount,
   NotImplementedError,
+  type Page,
+  pageOf,
   type ResolveEnvironmentOptions,
+  renderFixShellArg,
   stringField,
   systemClock,
 } from '@ultimat3/core';
@@ -17,7 +20,6 @@ import {
   DEFAULT_CONTENT_TYPE,
   etagOf,
   type ListOptions,
-  type ListPage,
   type PutOptions,
   resolveListLimit,
   type SignedUrlOptions,
@@ -29,10 +31,17 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
-import { etagOfFile, headObject, readObjectBytes } from './driver-local-read';
-import type { Sidecar } from './driver-local-sidecar';
+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 {
+  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';
@@ -96,6 +105,20 @@ function refuseUnsupportedPut(putOptions?: PutOptions): void {
 /** `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
@@ -133,19 +156,36 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     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)));
+    oneAtATime(key, () => headObject(root, key, () => etagOfFile(root, key, registered)));
+
+  /**
+   * 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. */
   const removeIfPresent = async (path: string, key: string): Promise<void> => {
     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>'")}`,
       );
     }
   };
@@ -167,27 +207,33 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       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 oneAtATime(safe, () =>
-        commitObject({ root, key: safe, disk: registered, body: bytes, 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 }),
       };
@@ -204,13 +250,13 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       // 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 (!(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);
+        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(DRIVER_NAME, safe);
+        if (entry === undefined) throw objectNotFound(registered, safe);
         return {
           object: { ...entry, contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE },
           bytes,
@@ -221,7 +267,7 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     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();
     },
 
@@ -233,31 +279,34 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       // 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);
+      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 oneAtATime(destination, () =>
-        commitObject({
+      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) => {
+        });
+      }).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);
+        if (!(await Bun.file(filePath(source)).exists())) throw objectNotFound(registered, source);
         throw error;
       });
       return {
         ...entry,
         key: destination,
         contentType: sidecar.contentType,
-        lastModified: clock.now(),
+        lastModified,
       };
     },
 
@@ -267,6 +316,16 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       // 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 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);
@@ -277,11 +336,20 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
       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
@@ -308,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
@@ -318,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();
@@ -328,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;
+}

package/src/driver-memory.ts

@@ -1,30 +1,46 @@
 // Single responsibility: the disk a TEST holds — a `StorageDriver` over one `Map`, answering every
-// question `localDriver` answers and refusing what it refuses, with nothing on a filesystem to
-// create or clean up. Not a deployment's disk: a restart is every object gone.
+// question `localDriver` answers and refusing what it refuses (a key that is another key's path
+// included), with nothing on a filesystem to create or clean up. Not a deployment's disk: a
+// restart is every object gone.
 //
 // It exists because the alternative was written by hand in every suite that needed a bucket: a
 // fake with three methods and five `unsupported()` stubs, each a slightly different contract.
 
-import { type Clock, finiteCount, NotImplementedError, systemClock } from '@ultimat3/core';
+import {
+  type Clock,
+  finiteCount,
+  NotImplementedError,
+  type Page,
+  pageOf,
+  systemClock,
+} from '@ultimat3/core';
 import {
   assertListOptions,
   assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   etagOf,
   type ListOptions,
-  type ListPage,
   type PutOptions,
   resolveListLimit,
   type SignedUrlOptions,
   type StorageBody,
   type StorageDriver,
+  type StorageListEntry,
   type StorageObject,
   type StorageRead,
   sha256Base64,
   toBytes,
 } from './driver';
 import type { LocalDriverOptions } from './driver-local';
-import { checksumMismatch, getTooLarge, objectNotFound } from './errors';
+import { keyInTheWay } from './driver-memory-conflict';
+import { checksumMismatch, getTooLarge, keyConflict, objectNotFound } from './errors';
+import {
+  assertObjectLockOptions,
+  isLocked,
+  type ObjectLock,
+  ObjectLockedError,
+  requestedLock,
+} from './object-lock';
 import { assertSafeKey } from './path';
 import type { SignedUrlVerification } from './signed-url';
 import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
@@ -34,7 +50,7 @@ import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 const DRIVER_NAME = 'memory';
 
 /** `localDriver`'s options, minus the directory there is none of. */
-export type MemoryDriverOptions = Omit<LocalDriverOptions, 'root'>;
+export type MemoryStorageDriverOptions = Omit<LocalDriverOptions, 'root'>;
 
 export interface MemoryStorageDriver extends StorageDriver {
   /**
@@ -47,6 +63,8 @@ export interface MemoryStorageDriver extends StorageDriver {
 interface Stored {
   readonly bytes: Uint8Array;
   readonly object: StorageObject;
+  /** The local disk's sidecar lock, held here instead. */
+  readonly lock?: ObjectLock | undefined;
 }
 
 /**
@@ -62,7 +80,7 @@ const snapshot = (object: StorageObject): StorageObject => ({
   ...(object.metadata === undefined ? {} : { metadata: { ...object.metadata } }),
 });
 
-export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDriver {
+export function memoryStorageDriver(options: MemoryStorageDriverOptions = {}): MemoryStorageDriver {
   const maxPutBytes = finiteCount(
     'the memory disk driver',
     'maxPutBytes',
@@ -79,10 +97,32 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
   let baseUrl = options.baseUrl ?? signedUrlBaseFor(DRIVER_NAME);
   const secret = resolveSigningSecret(DRIVER_NAME, options);
   const stored = new Map<string, Stored>();
+  // The name a registry gave this disk, so a miss names `disk('<it>')` — the call the author wrote.
+  let registered: string = DRIVER_NAME;
+
+  /** The lock that holds NOW, or `undefined` — the local disk's rule, read off the map. */
+  const lockAt = (key: string): ObjectLock | undefined => {
+    const lock = stored.get(key)?.lock;
+    return isLocked(lock, clock.now()) ? lock : undefined;
+  };
+  const refuseOverwrite = (key: string, action: 'overwrite' | 'copy onto'): void => {
+    const lock = lockAt(key);
+    if (lock !== undefined) throw new ObjectLockedError({ disk: registered, key, action, lock });
+  };
+
+  /**
+   * The local disk's path rule: a key cannot be another key's directory (`X_STORAGE_KEY_CONFLICT`).
+   * Emulated, not inherited — a `Map` holds both — because a suite on this disk stands in for the
+   * dev disk, and a key layout that passes here and fails in `x dev` is a gap found late.
+   */
+  const refuseConflict = (key: string): void => {
+    const blocking = keyInTheWay(stored, key);
+    if (blocking !== undefined) throw keyConflict(registered, key, blocking);
+  };
 
   const found = (key: string): Stored => {
     const hit = stored.get(key);
-    if (hit === undefined) throw objectNotFound(DRIVER_NAME, key);
+    if (hit === undefined) throw objectNotFound(registered, key);
     return hit;
   };
 
@@ -94,6 +134,7 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
     },
 
     registerAs(diskName: string): void {
+      registered = diskName;
       if (options.baseUrl === undefined) baseUrl = signedUrlBaseFor(diskName);
     },
 
@@ -113,6 +154,7 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
         });
       }
       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) {
@@ -130,8 +172,16 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
           : { cacheControl: putOptions.cacheControl }),
         ...(putOptions?.metadata === undefined ? {} : { metadata: putOptions.metadata }),
       };
+      // Checked AFTER the body is read, with no await between check and write: the map is the
+      // queue the local disk needs a `keyedQueue` for.
+      refuseConflict(safe);
+      refuseOverwrite(safe, 'overwrite');
       // A copy in, as a file write is: the caller's buffer and metadata are the caller's to reuse.
-      stored.set(safe, { bytes: bytes.slice(), object: snapshot(object) });
+      stored.set(safe, {
+        bytes: bytes.slice(),
+        object: snapshot(object),
+        lock: requestedLock(putOptions),
+      });
       return snapshot(object);
     },
 
@@ -160,6 +210,8 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
       // refusal whether or not the source exists.
       const [from_, destination] = [assertSafeKey(from), assertSafeKey(to)];
       const source = found(from_);
+      refuseConflict(destination);
+      refuseOverwrite(destination, 'copy onto');
       const object: StorageObject = {
         ...source.object,
         key: destination,
@@ -170,18 +222,28 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
     },
 
     async delete(key: string): Promise<void> {
-      stored.delete(assertSafeKey(key));
+      const safe = assertSafeKey(key);
+      const lock = lockAt(safe);
+      if (lock !== undefined) {
+        throw new ObjectLockedError({ disk: registered, key: safe, action: 'delete', lock });
+      }
+      stored.delete(safe);
+    },
+
+    async retentionOf(key: string): Promise<ObjectLock> {
+      const lock = found(assertSafeKey(key)).lock;
+      return lock === undefined ? { legalHold: false } : structuredClone(lock);
     },
 
     async exists(key: string): Promise<boolean> {
       return stored.has(assertSafeKey(key));
     },
 
-    async list(listOptions?: ListOptions): Promise<ListPage> {
+    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;
       // Code-unit order and "the cursor is the last key of the page before" — the local disk's own.
       const keys = [...stored.keys()]
         .filter((key) => key.startsWith(prefix) && (cursor === undefined || key > cursor))
@@ -191,10 +253,7 @@ export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDr
         const hit = stored.get(key);
         return hit === undefined ? [] : [snapshot(hit.object)];
       });
-      const last = page.at(-1);
-      return keys.length > page.length && last !== undefined
-        ? { objects, truncated: true, cursor: last }
-        : { objects, truncated: false };
+      return pageOf(objects, keys.length > page.length ? (page.at(-1) ?? null) : null);
     },
 
     async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {

package/src/driver-s3-absent.ts

@@ -0,0 +1,32 @@
+// Single responsibility: does a provider failure mean "there is nothing at that key"? Split from
+// `driver-s3.ts` at its line ceiling; the one reader is that driver's delete and read paths.
+
+import { stringField } from '@ultimat3/core';
+
+/** One numeric field off a value that may fight being read — `stringField`'s missing twin. */
+function numberField(value: unknown, key: string): number | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held = (value as Record<string, unknown>)[key];
+    return typeof held === 'number' ? held : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The provider codes that mean "there is nothing at that key", and nothing wider. */
+const ABSENT_OBJECT_CODES: ReadonlySet<string> = new Set(['NoSuchKey', 'NotFound', 'ENOENT']);
+
+/**
+ * The ONE delete failure the contract calls success. `AccessDenied`, `SlowDown`, an expired
+ * credential and a reset connection are none of them, and the previous `.catch(() => undefined)`
+ * reported all four as deleted — which is how an erasure sweep certifies data it never removed.
+ *
+ * Read structurally: an `S3Error` is `name: 'S3Error'` with a `code` the service returned, and
+ * every field of a value this process did not build is a getter that can throw.
+ */
+export function isAbsentObject(error: unknown): boolean {
+  const code = stringField(error, 'code');
+  if (code !== undefined && ABSENT_OBJECT_CODES.has(code)) return true;
+  return numberField(error, 'statusCode') === 404 || numberField(error, 'status') === 404;
+}

package/src/driver-s3-client.ts

@@ -0,0 +1,94 @@
+// Single responsibility: the s3 disk's view of `Bun.S3Client` — the structural types its methods
+// are called through (so `bun-types` stays out of the public contract and a test injects a fake),
+// and the one place the real client is constructed, lazily, from the disk's options.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+import type { S3DriverOptions } from './driver-s3';
+import { requireEnv, resolveS3Target } from './driver-s3-signed';
+
+/** Structural view of `Bun.S3Client` — typing it here keeps `bun-types` out of the contract. */
+export interface S3FileLike {
+  /** `S3FileLike` is in the union because Bun's own `write` takes an `S3File` — that is `copy`. */
+  write(data: Uint8Array | Blob | S3FileLike, options?: { type?: string }): Promise<number>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  exists(): Promise<boolean>;
+  delete(): Promise<void>;
+  stream(): ReadableStream<Uint8Array>;
+  stat(): Promise<S3StatLike>;
+  presign(options: { method?: string; expiresIn?: number; type?: string }): string;
+}
+
+export interface S3StatLike {
+  readonly size: number;
+  readonly type?: string | undefined;
+  readonly etag?: string | undefined;
+  readonly lastModified?: string | Date | undefined;
+}
+
+export interface S3ListEntryLike {
+  readonly key?: string | undefined;
+  readonly size?: number | undefined;
+  readonly eTag?: string | undefined;
+  readonly lastModified?: string | Date | undefined;
+}
+
+export interface S3ListResultLike {
+  readonly contents?: readonly S3ListEntryLike[] | undefined;
+  readonly isTruncated?: boolean | undefined;
+  readonly nextContinuationToken?: string | undefined;
+}
+
+export interface S3ClientLike {
+  file(key: string): S3FileLike;
+  list(input: {
+    prefix?: string;
+    maxKeys?: number;
+    continuationToken?: string;
+  }): Promise<S3ListResultLike>;
+}
+
+interface S3ClientConstructor {
+  new (options: Record<string, unknown>): S3ClientLike;
+}
+
+/**
+ * Everything but the key pair `Bun.S3Client` is built with — the SAME `resolveS3Target` the signed
+ * path reads, handed over explicitly so Bun never consults a second table.
+ */
+export function clientTarget(options: S3DriverOptions): Record<string, unknown> {
+  const target = resolveS3Target(options);
+  // Bun's flag is the inverse: path style means "not virtual hosted".
+  const pathStyle = options.forcePathStyle;
+  return {
+    bucket: options.bucket,
+    ...(target.region === undefined ? {} : { region: target.region }),
+    ...(target.endpoint === undefined ? {} : { endpoint: target.endpoint }),
+    ...(pathStyle === undefined ? {} : { virtualHostedStyle: !pathStyle }),
+    ...(target.sessionToken === undefined ? {} : { sessionToken: target.sessionToken }),
+  };
+}
+
+export function buildClient(options: S3DriverOptions): S3ClientLike {
+  if (options.client !== undefined) return options.client;
+  if (options.bucket === '') {
+    throw new ConfigInvalidError({
+      cause: 's3 disk was defined without a bucket',
+      fix: 'set storage.disks.<name>.bucket in app.config.ts',
+    });
+  }
+  const env = options.env ?? process.env;
+  const idVar = options.accessKeyIdEnv ?? 'S3_ACCESS_KEY_ID';
+  const secretVar = options.secretAccessKeyEnv ?? 'S3_SECRET_ACCESS_KEY';
+  const Client = (Bun as unknown as { S3Client?: S3ClientConstructor }).S3Client;
+  if (Client === undefined) {
+    throw new ConfigInvalidError({
+      cause: 'Bun.S3Client is unavailable in this runtime',
+      fix: 'upgrade the runtime: bun upgrade   # the s3 disk needs bun >= 1.3',
+    });
+  }
+  return new Client({
+    accessKeyId: requireEnv(env, idVar, secretVar),
+    secretAccessKey: requireEnv(env, secretVar, idVar),
+    ...clientTarget(options),
+  });
+}