@ultimat3/storage 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -38,14 +38,19 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 
 | File | Owns |
 |---|---|
-| `driver.ts` | `StorageDriver` contract (9 methods; `registerAs`/`verifySigned` optional), `assertPutOptions`, + bounded `toBytes`/`sha256Base64`/`etagOf` |
+| `driver.ts` | `StorageDriver` contract (9 methods; `registerAs`/`verifySigned`/`retentionOf` optional), `assertPutOptions`, + bounded `toBytes`/`sha256Base64`/`etagOf` |
 | `driver-local.ts` | dev default over `Bun.file`, `.meta/` sidecars, `Bun.Glob` listing |
 | `driver-local-write.ts` | the local WRITE: staged under `.meta/.tmp/`, renamed marker → sidecar → bytes, `X_STORAGE_KEY_CONFLICT` / `X_STORAGE_PUT_FAILED`, the per-key queue |
 | `driver-local-read.ts` | `headObject`: sidecar + pending marker → trusted, re-checked, or untyped |
 | `driver-local-sidecar.ts` | the sidecar shape and its one parser |
 | `signing-secret.ts` | `DEV_SIGNING_SECRET`, `usesDevStorageSecret`, `resolveSigningSecret` |
-| `driver-memory.ts` | `memoryDriver()` — a test's disk over a `Map`: `localDriver`'s contract and refusals, `objects()` for an assertion about the bucket. `driver-memory.test.ts` runs each claim on BOTH disks. Signs through `resolveSigningSecret` (`signing-secret.ts`), the one rule both share |
-| `driver-s3.ts` | `Bun.S3Client`, built lazily (import must never open a socket) |
+| `driver-memory-conflict.ts` | `claim()`'s conflict rule over keys |
+| `driver-memory.ts` | `memoryStorageDriver()` — a test's disk over a `Map`: `localDriver`'s contract and refusals, `objects()` for an assertion about the bucket. `driver-memory.test.ts` runs each claim on BOTH disks. Signs through `resolveSigningSecret` (`signing-secret.ts`), the one rule both share |
+| `driver-s3.ts` | the s3 disk: Bun where it can, the signed wire where it cannot |
+| `driver-s3-client.ts` | `S3*Like` + `buildClient`, lazy (import never opens a socket) |
+| `driver-s3-signed.ts` | signed requests: Bun's addressing restated, `requireEnv`, `fetch`, refusal as `S3Error` fields |
+| `driver-s3-lock.ts` | the signed PUT's headers; `?retention` / `?legal-hold` |
+| `object-lock.ts` | lock types, the `put()` screen, `isLocked`, the local/memory refusals |
 | `driver-s3-region.ts` | a provider's wrong-region refusal → `X_CONFIG_INVALID` whose fix names `S3_REGION` |
 | `path.ts` | key validation + `META_DIR` + `scopedKey`/`isWithinOrg`/`isTenantScoped` tenant boundary |
 | `signed-url.ts` | HMAC over the constraint tuple, constant-time verify |
@@ -70,8 +75,8 @@ Gotchas:
   (`As of 2026-10`). `put('a')` then `put('a/b')` — or the reverse, or `a` beside `a.json/b` in the
   sidecar tree — is `X_STORAGE_KEY_CONFLICT`, decided by `claim()` for BOTH paths before either is
   touched. Suffixed on-disk names would lift it and orphan every existing root's objects without a
-  migration; do not change the layout without one. `driver-contract.test.ts` runs the claim on all
-  three disks.
+  migration; do not change the layout without one. Memory emulates it; s3 holds both. A key that
+  is only a directory is ABSENT to `delete()` (test a refusal with `driver-local-fixture.ts`).
 - **The local commit order is marker → sidecar → bytes → clear marker. Do not reorder**
   (`As of 2026-10`). Bytes-first serves new bytes under the old type; sidecar-first alone serves
   old bytes under the new one. The marker holds the new etag, so `headObject` knows the one state
@@ -91,8 +96,7 @@ Gotchas:
   one secret, so the canonical string must name the disk. Path, not origin — the verifying route
   sees a path — and `signedUrlBasePath` is how an absolute `baseUrl` is compared.
 - **`isWithinOrg` never throws**: an org id that cannot be one contains nothing.
-- **A variant key keeps the whole source key** (`hero.png@w640.webp`), so two sources differing
-  only by extension are two cache identities.
+- **A variant key keeps the whole source key** (`hero.png@w640.webp`): two cache identities.
 - **A driver's semantics are pinned in ONE test with the other driver beside them.**
   `driver-parity.test.ts` drives `localDriver` over a temp dir and `s3Driver` over `FakeS3Client`
   in a single `test()` per claim, so neither disk can move alone. Where the two genuinely cannot
@@ -107,35 +111,28 @@ Gotchas:
   page), so a paging caller read "complete, and there is nothing here" over a full disk, while the
   s3 disk handed `maxKeys: 0` to the provider. Core's `assert` (`X_INVARIANT`), for the reason
   `@ultimat3/seo`'s `chunk()` uses it: a bound with no code of its own is still a coded refusal.
+- **`list()` answers core's `Page<StorageListEntry>`, and no storage-local page type exists**
+  (`As of 25.0.0`; `ListPage` is deleted). Every driver builds it with core's `pageOf`, so
+  `hasMore` is derived from the cursor and cannot disagree with it. The cursor is minted only when
+  a row past the page exists — never from `rows.length === limit`, the full-last-page defect a
+  query's cursor had — and the full-last-page case is pinned on memory, local and live s3.
 - **`META_DIR` is reserved case-INSENSITIVELY** (`As of 2026-08`), exactly as `isTenantScoped`
-  folds and for the same filesystem: `.META/a.txt.json` was a legal key that writes
-  `<root>/.META/a.txt.json`, which on APFS and NTFS IS `<root>/.meta/a.txt.json` — the sidecar for
-  object `a.txt` — so a caller able to name a key rewrote another object's recorded `contentType`.
-  The whole SEGMENT is compared, never a prefix: `.metadata/a.json` is an ordinary key and stays
-  one, and `path.test.ts` pins both halves.
-- **`disk(name)` resolves through a `Map`, never `config.disks[name]`.** The bracket read walked
-  the prototype chain, so `disk('constructor')` handed back the `Object` function and the next
-  `.put()` was a bare `TypeError` — `X_STORAGE_DISK_UNKNOWN` unreachable for `constructor`,
-  `toString`, `valueOf`, `hasOwnProperty` and `__proto__`, in a function whose own
-  `default:` check already read `Object.keys`.
+  folds: on APFS/NTFS `.META/` IS `.meta/`. The whole SEGMENT is compared, never a prefix
+  (`.metadata/a.json` is an ordinary key); `path.test.ts` pins both halves.
+- **`disk(name)` resolves through a `Map`, never `config.disks[name]`**: the bracket read walked
+  the prototype chain (`disk('constructor')` was the `Object` function, not `X_STORAGE_DISK_UNKNOWN`).
 - **`list()` is idempotent for an EMPTY disk and for nothing else** (`As of 2026-08`) — exactly
-  `delete()`'s rule, one call to the left, and both drivers broke it in opposite directions. The
-  local one caught EVERYTHING and answered `{ objects: [], truncated: false }`, so `EACCES` on the
-  root read as "this disk is empty"; the s3 one let a bare `S3Error` escape uncoded, with nothing
-  for the http error map to render but a 500. `sweepOrphans` walks `list()`, so the local swallow
-  was a false-erasure report a layer up. `ENOENT` (a root nobody has written to) is still an empty
-  page; everything else is `X_STORAGE_LIST_FAILED`, whose `fix` the DRIVER supplies.
-- **`head()` and `list()` NEVER read an object's bytes.** A listing that cannot know an etag
-  reports `''`, as the s3 listing does. `get()` hashes bytes it already holds; `copy()` passes
-  `hash: true` so the destination sidecar never records `etag: ''`.
-- **`put({ metadata })` / `put({ cacheControl })` is the one `PutOptions` pair the disks disagree
-  about, and it is pinned rather than resolved.** Bun's `S3File.write` exposes `type`, `acl` and
-  `storageClass` and no header hook for `x-amz-meta-*` or `Cache-Control`, so `s3Driver` refuses
-  (`X_NOT_IMPLEMENTED`, with the out-of-band `aws s3 cp` in the fix) while `localDriver` stores both
-  in its sidecar and reads them back. **Do not "fix" this by making the local disk refuse too** —
-  that deletes a working capability and the two `StorageListEntry` fields that carry it, to buy
-  symmetry with a limitation that is Bun's and temporary. The day the hook lands, the s3 half of
-  `driver-parity.test.ts` fails and the resolution is to make s3 store them.
+  `delete()`'s rule. `ENOENT` (a root nobody has written to) is an empty page; everything else is
+  `X_STORAGE_LIST_FAILED`, whose `fix` the DRIVER supplies.
+- **`head()` and `list()` NEVER read an object's bytes** — an unknowable etag is `''`, as on s3.
+  `get()` hashes bytes it holds; `copy()` passes `hash: true`, so no sidecar records `etag: ''`.
+- **s3 `put()` with `metadata`/`cacheControl`/`retention`/`legalHold` is ONE signed PUT** (core's
+  `signAwsRequest`; Bun's `write` takes no header); a plain `put()` stays on Bun. Reads stay Bun's
+  HEAD, so s3 `get()` reports neither field — pinned in `driver-parity.test.ts`.
+- **Object Lock: local/memory REFUSE delete/overwrite/copy-onto** (`X_STORAGE_OBJECT_LOCKED`);
+  S3 accepts both (delete marker, new version; the locked version stays). Pinned divergence: one
+  version per key. A pair in doubt never unlocks. `NoSuchObjectLockConfiguration` is a 404.
+- **A live suite signs on a wall clock** (`performance`): `Date` is frozen → `RequestTimeTooSkewed`.
 - **`signedUrl({ maxBytes })` is signed on `local` and unenforceable on `s3`, and the s3 driver may
   NOT refuse it.** `grantUpload` passes `maxBytes: policy.maxBytes` on every grant, so a refusal
   would break every s3 upload an app mints. S3 has no request header for a size and Bun's `presign`
@@ -193,7 +190,7 @@ Gotchas:
   the secret, `isLocal()` and the refusal's environment all read `options.env ?? process.env`, so
   the boot's guard and the constructor it guards cannot answer from two tables.
   `driver-local-boot.test.ts` pins it by mutation.
-- **The mounted read half is `@ultimat3/cli`'s `dev-storage.ts`, not this package.** `GET
+- **The mounted read half is `@ultimat3/cli`'s `runtime-storage.ts`, not this package.** `GET
   /_storage/:disk/*key` gates on `@ultimat3/policy`'s `evaluate()` (`storage:read`), which is tier
   2 and unreachable from here — so a "serve this object" helper in this package could only ever be
   a second authz path. This package's contribution to that route is `assertSafeKey`,
@@ -229,7 +226,7 @@ Gotchas:
   held to `[A-Za-z0-9-]`: a provider's sentence may put nothing else into a `fix:`. A HEAD has no
   body, so `exists()`/`stat()` never see it. `driver-s3.live.test.ts` runs with no region on purpose.
 - The signature check runs BEFORE the expiry check. Do not reorder.
-- `timingSafeEqual` is `@ultimat3/core`'s (`signed-url.ts` imports and re-exports it) — the same
+- `timingSafeEqual` is `@ultimat3/core`'s (`signed-url.ts` imports it) — the same
   implementation `@ultimat3/auth` uses, not a second copy. Add new secret comparisons through it.
 - `verifySignedUrl` never throws, and `parseConstraints` is where that is kept: the key is decoded
   through the guarded `decodeSegment`, so a `%ZZ` in the path is `'malformed'` rather than the bare
@@ -250,7 +247,7 @@ Gotchas:
   (`X_CONFIG_INVALID`) — it could only mint under one of them. `@ultimat3/cli`'s
   `STORAGE_BASE_PATH` is a third statement of the mount prefix and should import
   `DEFAULT_SIGNED_URL_BASE` instead.
-- **`accept.ts` asks the `isTenantScoped`/`isWithinOrg` PAIR, exactly as `dev-storage.ts` does.**
+- **`accept.ts` asks the `isTenantScoped`/`isWithinOrg` PAIR, exactly as `runtime-storage.ts` does.**
   `isWithinOrg` alone refused every un-scoped key, so an app's own `brand/logo.png` was unreachable
   through a URL it had just signed. `isTenantScoped` is case-INSENSITIVE and `isWithinOrg` is not:
   `Org/o2/x` and `org/o2/x` are one file on APFS/NTFS, so the fold has to count as tenant-scoped
@@ -264,9 +261,8 @@ Gotchas:
   signed URL is a capability; a leaked capability must still not cross a tenant.
 - `X_STORAGE_ORG_MISMATCH` maps to **404**, not 403 (`@ultimat3/http`'s `error-map.ts`). 403 would
   confirm a key exists to the one caller who must not learn it.
-- The local driver reports the **filesystem's** `lastModified`, not the injected `Clock`, so
-  `sweepOrphans` cannot be tested against it with a frozen clock — `attachment.test.ts` uses a
-  stub driver with authored timestamps, and `driver-local.test.ts` proves the disk half.
+- **Local `lastModified` is the `Clock`'s, kept in the sidecar** — one instant from `put`/`copy`
+  to every read; mtime only with no trusted sidecar.
 - `upload-client.ts` defaults to `XMLHttpRequest`, not `fetch`: `fetch` reports no upload
   progress in any shipping browser, and a bar that jumps 0 → 100 is a bar that is lying. It is
   **the declared XHR seam** of plan 101 (decision 13): the one `XMLHttpRequest` the framework

package/README.md

@@ -23,10 +23,10 @@ Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs
 | Driver | Backing | For | Signed URLs |
 |---|---|---|---|
 | `localDriver` | `Bun.file`/`Bun.write`, one root dir | dev, tests, single-node | HMAC + dev route |
-| `s3Driver` | `Bun.s3` | prod: any S3-compatible endpoint — AWS, R2, a self-hosted gateway | provider presign |
-| `memoryDriver` | a `Map` in this process | a TEST's disk — never a deployment's: a restart is every object gone | HMAC, the local disk's own |
+| `s3Driver` | `Bun.s3`, plus core's `signAwsRequest` over `fetch` for the requests Bun has no option for | prod: any S3-compatible endpoint — AWS, R2, a self-hosted gateway | provider presign |
+| `memoryStorageDriver` | a `Map` in this process | a TEST's disk — never a deployment's: a restart is every object gone | HMAC, the local disk's own |
 
-`memoryDriver()` is what a suite holds instead of a temp directory or a hand-written fake: it
+`memoryStorageDriver()` is what a suite holds instead of a temp directory or a hand-written fake: it
 answers every method `localDriver` does, refuses what it refuses (an unsafe key, a wrong checksum,
 a body past `maxPutBytes`, `serverSideEncryption`), and signs under the same rule — the published
 development key in `development` and `test` only. `objects()` hands back a COPY of every stored
@@ -34,13 +34,13 @@ object's bytes by key, for the assertion a test makes about the bucket itself.
 
 ```ts
 import { afterEach, beforeEach } from 'bun:test';
-import { defineStorage, disk, memoryDriver, resetStorage } from '@ultimat3/storage';
+import { defineStorage, disk, memoryStorageDriver, resetStorage } from '@ultimat3/storage';
 
 // A fresh driver per test: `resetStorage()` forgets the REGISTRY, never a driver's objects, so a
 // driver held across tests carries every earlier test's writes.
-let sessions = memoryDriver();
+let sessions = memoryStorageDriver();
 beforeEach(() => {
-  sessions = memoryDriver();
+  sessions = memoryStorageDriver();
   defineStorage({ disks: { sessions } });
 });
 afterEach(() => resetStorage());
@@ -64,10 +64,19 @@ network, but never this process's heap. Both arguments go through `assertSafeKey
 One S3 driver covers all three backends — the difference is `endpoint` + `forcePathStyle`.
 Credentials are **env var NAMES** (`accessKeyIdEnv`, default `S3_ACCESS_KEY_ID`), never
 literals: a key in `app.config.ts` is a key in git. Missing ones throw `X_ENV_MISSING`.
+Endpoint, region and session token resolve ONCE for both transports, as Bun reads them: the
+option, then `S3_ENDPOINT`/`AWS_ENDPOINT`, `S3_REGION`/`AWS_REGION`,
+`S3_SESSION_TOKEN`/`AWS_SESSION_TOKEN` (or the one `sessionTokenEnv` names), from
+`s3Driver({ env })` or `process.env`. `s3Driver({ fetch, clock })` inject the signed path's transport and its clock (tests; default the
+global `fetch` and `systemClock`); `S3FetchLike` is the shape.
 `localDriver` keeps content type, etag, `cacheControl` and `metadata` in a `<root>/.meta/`
 sidecar so `get()`/`list()` round-trip everything `put()` was handed; sidecars never appear in
-`list()`. `s3Driver` cannot: it refuses `cacheControl`/`metadata` on `put()` (`X_NOT_IMPLEMENTED`,
-Bun exposes no header hook yet).
+`list()`. `s3Driver` STORES both — a `put()` carrying `cacheControl`, `metadata`, `retention` or
+`legalHold` goes past the Bun client as one SigV4-signed PUT (`x-amz-meta-*`, `Cache-Control`,
+`Content-MD5`), against the same endpoint, region and credentials — but its `get()`/`stat()` read
+through Bun's HEAD, which exposes neither, so there they are absent rather than invented. A plain
+`put()` stays on the Bun client. A metadata name must be a header token and every value printable
+ASCII (`X_INVARIANT` otherwise): S3 carries them as headers.
 
 **The local disk writes an object by rename, in an order no crash can make lie.** An object there
 is two files, so a `put()` or `copy()` stages bytes, sidecar and a *pending marker* (the new etag)
@@ -99,12 +108,16 @@ non-string `list()` prefix or cursor are `X_INVARIANT` (`driver-read-failed.test
 method on every disk). The one thing no code can cover is a `stream()` that fails after it was
 handed back: that is the stream's own error.
 
-**A key cannot be another key's path on the local disk.** A POSIX path is a file or a directory:
-`put('a')` then `put('a/b')` — or the reverse, or `a` beside `a.json/b`, which collide in the
-sidecar tree — is `X_STORAGE_KEY_CONFLICT`, refused before a byte moves, where it used to be a
-bare `ENOTDIR` / `EISDIR`. Its `fix` names the disk as `defineStorage` registered it, not the
-driver kind. `s3Driver` and `memoryDriver` hold both keys; `driver-contract.test.ts`
-pins the divergence.
+**A key cannot be another key's path on the local disk — or on the memory disk standing in for
+it.** A POSIX path is a file or a directory: `put('a')` then `put('a/b')` — or the reverse, a
+`copy()` onto either, or `a` beside `a.json/b`, which collide in the sidecar tree — is
+`X_STORAGE_KEY_CONFLICT`, refused before a byte moves, where it used to be a bare `ENOTDIR` /
+`EISDIR`. Its `fix` names the disk as `defineStorage` registered it, not the driver kind.
+`memoryStorageDriver` refuses the same keys with the same `blocking` (a suite on it stands in for
+`x dev`'s disk); `s3Driver` holds both. `driver-local-memory-parity.test.ts` holds local and memory
+to one answer, `driver-contract.test.ts` pins the s3 divergence. `delete()` of a key that is only
+another key's directory (`delete('c')` beside `c/d`) is deleting an absent key: not an error, and
+nothing beneath it is touched.
 
 `stat(key)` answers what a read would — size, type, etag, age — **without the bytes**, and
 `undefined` for nothing there. It is a required `StorageDriver` method: `promoteAttachment` measures
@@ -112,7 +125,10 @@ with it, and a driver that cannot measure does not compile.
 
 `lastModified` is **optional** on a listing entry and on a `StorageObject`: absent when the
 provider reported none, never epoch 0 — which `sweepOrphans` read as "older than any window" and
-deleted. A reader that needs an age handles `undefined`; the sweep spares it.
+deleted. A reader that needs an age handles `undefined`; the sweep spares it. On the local and
+memory disks it is the write's instant on the disk's injected `clock`: what `put()`/`copy()`
+returned is what every later `stat`/`get`/`list` reports (the local disk records it in the
+sidecar; an object written before that, or with no trusted sidecar, reports the file's mtime).
 
 **`StorageListEntry.contentType` is optional; `StorageObject.contentType` is not.** S3's
 `ListObjectsV2` returns no Content-Type, so a listed s3 object simply has none — reading the real
@@ -131,6 +147,28 @@ disk answered `exists()` true and `list()` nothing for the same object. **`limit
 integer or a refusal** (`X_INVARIANT`, at the `ListOptions` seam): `limit: 0` used to read back as
 a complete, empty page on the local disk and as `maxKeys: 0` on s3.
 
+**A listing is core's ONE `Page`** — `Page<StorageListEntry>`, the shape an entity `findMany` and
+a query `.page()` answer: `{ rows, nextCursor, hasMore }`, `nextCursor` a string exactly when
+`hasMore` is true. The cursor exists only when another object does — the local and memory disks
+look one key past the page, s3 reads `IsTruncated` and takes `NextContinuationToken` — so a full
+last page answers `hasMore: false`, never a cursor to an empty page. `cursor: null` is the first
+page, so a walk threads `nextCursor` straight back:
+
+```ts
+import type { Page } from '@ultimat3/core';
+import { disk, type StorageListEntry } from '@ultimat3/storage';
+
+const keys: string[] = [];
+let cursor: string | null = null;
+do {
+  const page: Page<StorageListEntry> = await disk('uploads').list({ prefix: 'org/o1/', cursor });
+  keys.push(...page.rows.map((object) => object.key));
+  cursor = page.nextCursor;
+} while (cursor !== null);
+```
+
+Before 25.0.0 it was `ListPage { objects, truncated, cursor? }`, its own shape beside core's.
+
 ## `put()` is for objects that fit in memory
 
 `put()` buffers the whole body — size and checksum have to be known before the object exists —
@@ -151,6 +189,36 @@ the disk's own size (a HEAD on s3) before a byte is read — and is read with `s
 because an object's size is not the server's to choose: a presigned PUT lands in a bucket
 unmeasured, so a later `get()` of it was heap growth the uploader picked.
 
+## Write-once objects (S3 Object Lock)
+
+```ts
+import { systemClock } from '@ultimat3/core';
+import { disk, isLocked } from '@ultimat3/storage';
+
+const key = 'org/o1/ledger.csv';
+const bytes = new TextEncoder().encode('a,b\n');
+const now = systemClock.now();
+await disk('ledger').put(key, bytes, {
+  retention: { mode: 'COMPLIANCE', retainUntil: new Date(now.getTime() + 7 * 86_400_000) },
+  legalHold: true,
+});
+const lock = await disk('ledger').retentionOf?.(key); // { retention: { mode, retainUntil }, legalHold: true }
+isLocked(lock, now); // a hold, or a retention still ahead
+```
+
+| | s3 | local, memory |
+|---|---|---|
+| `put({ retention, legalHold })` | `x-amz-object-lock-mode` / `-retain-until-date` (ISO) / `-legal-hold` (`ON`/`OFF`) on the signed PUT — the bucket must be CREATED with Object Lock | recorded in the sidecar (local) or beside the bytes (memory) |
+| `retentionOf(key)` | signed `GET ?retention` + `?legal-hold`; a bucket without Object Lock, or an object with none, is `{ legalHold: false }` | from what `put()` recorded |
+| `delete` / overwrite of a locked object | sent: S3 locks a VERSION, so a DELETE writes a delete marker and a PUT a newer version — the locked version stays | **refused** — `X_STORAGE_OBJECT_LOCKED` (`ObjectLockedError`, HTTP 409; `.lock` carries the lock) — until it lapses: one version per key, so refusing is the only way to keep the bytes |
+
+`retainUntil` must be a valid instant in the future and `mode` `GOVERNANCE` or `COMPLIANCE`
+(`X_INVARIANT` before a byte moves). `COMPLIANCE` cannot be shortened by anyone; extending a
+retention, releasing a hold or bypassing `GOVERNANCE` is out of band:
+`aws s3api put-object-retention` / `put-object-legal-hold`. A `copy()` does not carry the source's
+lock — on S3 it is per version and set by the request. The local refusal is in-process
+(`keyedQueue`), like every other local write rule.
+
 ## Server-side encryption, storage classes, lifecycle
 
 `PutOptions.serverSideEncryption` exists so the gap is visible **at the type level**, and every
@@ -349,9 +417,10 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_QUARANTINED` | `promoteAttachment` on a key nothing has released from `pending/quarantine/` |
 | `X_STORAGE_NOT_PENDING` | `promoteAttachment` on a key outside the org's `pending/` prefix — most often another row's attached key |
 | `X_STORAGE_PUT_FAILED` | the disk REFUSED a `put()`/`copy()` — `EACCES`, `ENOSPC`, `EROFS`, a provider's refused PUT |
+| `X_STORAGE_OBJECT_LOCKED` | local, memory: a delete, overwrite or copy onto a key under retention or a legal hold; the cause names the key, the mode and `retainUntil` or the hold, and the bytes are unchanged. Never raised by s3, where the provider keeps the locked version |
 | `X_STORAGE_READ_FAILED` | the disk REFUSED a `get`/`stat`/`exists`/`stream` or the read half of a `copy` — a denied `s3:GetObject`, a throttle, an unreadable file. An **absent** object is still `X_STORAGE_NOT_FOUND`, including one deleted between the existence check and the read |
-| `X_STORAGE_KEY_CONFLICT` | local disk only: the key's path is another key's directory, or the reverse (`a` and `a/b`) |
-| `X_NOT_IMPLEMENTED` | S3 user metadata / cache-control; `serverSideEncryption` on either driver |
+| `X_STORAGE_KEY_CONFLICT` | local and memory disks (never s3): the key's path is another key's directory, or the reverse (`a` and `a/b`) |
+| `X_NOT_IMPLEMENTED` | `serverSideEncryption` on any driver |
 | `X_ENV_MISSING` | core's: S3 credential env vars, or a `localDriver` built outside development where neither `signingSecret` nor `STORAGE_SIGNING_SECRET` holds a secret other than the published `DEV_SIGNING_SECRET` |
 | `X_IMAGE_UNSUPPORTED` | core's: an `avif` encode, a source no built-in decoder reads, or a `variantKey` format no variant can carry |
 | `X_IMAGE_DECODE_FAILED` | core's: truncated or corrupt image bytes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0"
+    "@ultimat3/core": "25.1.0"
   }
 }

package/src/attachment.ts

@@ -6,7 +6,7 @@
 
 import type { Clock } from '@ultimat3/core';
 import { assert, finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
-import type { ListPage, StorageDriver, StorageListEntry, StorageObject } from './driver';
+import type { StorageDriver, StorageListEntry, StorageObject } from './driver';
 import { notPending, objectNotFound, orgMismatch, quarantined, tooLarge } from './errors';
 import { isWithinOrg, orgPrefix, scopedKey } from './path';
 import type { UploadPolicy } from './upload';
@@ -229,13 +229,10 @@ export async function sweepOrphans(input: SweepOrphansInput): Promise<SweepResul
   const prefix = pendingPrefix(input.orgId);
   const deleted: string[] = [];
   const failed: SweepFailure[] = [];
-  let cursor: string | undefined;
+  let cursor: string | null = null;
   do {
-    const page: ListPage = await input.disk.list({
-      prefix,
-      ...(cursor === undefined ? {} : { cursor }),
-    });
-    for (const object of page.objects) {
+    const page = await input.disk.list({ prefix, cursor });
+    for (const object of page.rows) {
       // An object whose age the provider did not report is SPARED: only a proven age is swept.
       if (object.lastModified === undefined || object.lastModified.getTime() > cutoff) continue;
       if ((await input.keep?.(object)) === true) continue;
@@ -246,7 +243,7 @@ export async function sweepOrphans(input: SweepOrphansInput): Promise<SweepResul
         failed.push({ key: object.key, reason: renderThrowable(error) });
       }
     }
-    cursor = page.truncated ? page.cursor : undefined;
-  } while (cursor !== undefined);
+    cursor = page.nextCursor;
+  } while (cursor !== null);
   return { deleted, failed };
 }

package/src/driver-local-read.ts

@@ -9,7 +9,8 @@ import { parseSidecar, type Sidecar } from './driver-local-sidecar';
 import { pendingPathOf, sidecarPathOf } from './driver-local-write';
 import { isStorageError, objectNotFound, readFailed } from './errors';
 
-async function readSidecar(root: string, key: string): Promise<Sidecar | undefined> {
+/** The sidecar as recorded — trusted or not. The lock check reads it whole: a doubt never unlocks. */
+export async function readSidecar(root: string, key: string): Promise<Sidecar | undefined> {
   const file = Bun.file(`${root}/${sidecarPathOf(key)}`);
   if (!(await file.exists())) return undefined;
   try {
@@ -33,11 +34,11 @@ async function pendingEtag(root: string, key: string): Promise<string | undefine
  * would have been one call earlier.
  */
 const refusedRead =
-  (root: string, key: string) =>
+  (root: string, key: string, disk: string) =>
   (error: unknown): never => {
     if (isStorageError(error)) throw error;
     throw stringField(error, 'code') === 'ENOENT'
-      ? objectNotFound('local', key)
+      ? objectNotFound(disk, key)
       : readFailed(
           'local',
           key,
@@ -46,20 +47,27 @@ const refusedRead =
         );
   };
 
-/** The whole object, buffered — `get()`'s one read. */
-export async function readObjectBytes(root: string, key: string): Promise<Uint8Array> {
+/**
+ * The whole object, buffered — `get()`'s one read. `disk` is the name `defineStorage` registered,
+ * because a not-found `fix:` is `disk('<it>').list(…)`; `local` only for a driver nobody named.
+ */
+export async function readObjectBytes(
+  root: string,
+  key: string,
+  disk = 'local',
+): Promise<Uint8Array> {
   return Bun.file(`${root}/${key}`)
     .arrayBuffer()
-    .then((buffer) => new Uint8Array(buffer), refusedRead(root, key));
+    .then((buffer) => new Uint8Array(buffer), refusedRead(root, key, disk));
 }
 
 /** `etagOf`, streamed: a copy or a `stat()` must settle a doubt without buffering the object. */
-export async function etagOfFile(root: string, key: string): Promise<string> {
+export async function etagOfFile(root: string, key: string, disk = 'local'): Promise<string> {
   const hasher = new Bun.CryptoHasher('sha256');
   try {
     for await (const chunk of Bun.file(`${root}/${key}`).stream()) hasher.update(chunk);
   } catch (error) {
-    return refusedRead(root, key)(error);
+    return refusedRead(root, key, disk)(error);
   }
   return hasher.digest('hex').slice(0, 32);
 }
@@ -96,7 +104,9 @@ export async function headObject(
     key,
     size: file.size,
     etag,
-    lastModified: new Date(file.lastModified),
+    // The recorded instant when the sidecar is trusted, the file's mtime otherwise: one source per
+    // object, and the one `put()`/`copy()` returned — on the disk's injected clock.
+    lastModified: new Date(sidecar?.lastModified ?? file.lastModified),
     ...(sidecar?.contentType === undefined ? {} : { contentType: sidecar.contentType }),
     ...(sidecar?.cacheControl === undefined ? {} : { cacheControl: sidecar.cacheControl }),
     ...(sidecar?.metadata === undefined ? {} : { metadata: sidecar.metadata }),

package/src/driver-local-sidecar.ts

@@ -1,12 +1,62 @@
 // Single responsibility: the local disk's sidecar — the JSON file under `.meta/` holding what a
-// POSIX file has nowhere to keep (content type, etag, cache-control, user metadata), and the one
-// parser that reads it back as untrusted bytes off a disk.
+// POSIX file has nowhere to keep (content type, etag, cache-control, user metadata, the object
+// lock), and the one parser that reads it back as untrusted bytes off a disk.
 
-export interface Sidecar {
+import { isRetentionMode, type ObjectLock, type RetentionMode } from './object-lock';
+
+/** The lock as JSON holds it: the instant as an ISO string, the hold only when it is on. */
+export interface SidecarLock {
+  readonly retention?: { readonly mode: RetentionMode; readonly retainUntil: string } | undefined;
+  readonly legalHold?: true | undefined;
+}
+
+export interface Sidecar extends SidecarLock {
   readonly contentType: string;
   readonly etag: string;
   readonly cacheControl?: string | undefined;
   readonly metadata?: Readonly<Record<string, string>> | undefined;
+  /**
+   * The write's instant as ISO, read off the disk's injected `Clock` — what `put()`/`copy()`
+   * returned, so a later `stat`/`get`/`list` reports the same instant (the memory disk's rule).
+   * Absent on a sidecar written before it was recorded: the file's mtime answers instead.
+   */
+  readonly lastModified?: string | undefined;
+}
+
+/** `ObjectLock` → the fields a sidecar records. Nothing when nothing locks the object. */
+export function sidecarLock(lock: ObjectLock | undefined): SidecarLock {
+  if (lock === undefined) return {};
+  return {
+    ...(lock.retention === undefined
+      ? {}
+      : {
+          retention: {
+            mode: lock.retention.mode,
+            retainUntil: lock.retention.retainUntil.toISOString(),
+          },
+        }),
+    ...(lock.legalHold ? { legalHold: true } : {}),
+  };
+}
+
+/** The recorded lock as `ObjectLock`. A retention that does not parse is no retention. */
+export function lockOfSidecar(sidecar: SidecarLock | undefined): ObjectLock {
+  const recorded = sidecar?.retention;
+  return {
+    ...(recorded === undefined
+      ? {}
+      : { retention: { mode: recorded.mode, retainUntil: new Date(recorded.retainUntil) } }),
+    legalHold: sidecar?.legalHold === true,
+  };
+}
+
+function parseRetention(raw: unknown): SidecarLock['retention'] {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const mode = (raw as Record<string, unknown>)['mode'];
+  const until = (raw as Record<string, unknown>)['retainUntil'];
+  if (!isRetentionMode(mode) || typeof until !== 'string') return undefined;
+  if (!Number.isFinite(Date.parse(until))) return undefined;
+  return { mode, retainUntil: until };
 }
 
 // `!Array.isArray` is the load-bearing clause, matching `isPlainObject` in
@@ -29,10 +79,18 @@ export function parseSidecar(raw: unknown): Sidecar | undefined {
   // truncated what was just written, even though `Sidecar` itself declares both.
   const cacheControl = record['cacheControl'];
   const metadata = record['metadata'];
+  const retention = parseRetention(record['retention']);
+  const lastModified = record['lastModified'];
   return {
     contentType,
     etag,
     ...(typeof cacheControl === 'string' ? { cacheControl } : {}),
     ...(isStringRecord(metadata) ? { metadata } : {}),
+    // An instant that does not parse is no instant — never an invalid `Date` handed to a reader.
+    ...(typeof lastModified === 'string' && Number.isFinite(Date.parse(lastModified))
+      ? { lastModified }
+      : {}),
+    ...(retention === undefined ? {} : { retention }),
+    ...(record['legalHold'] === true ? { legalHold: true } : {}),
   };
 }