@ultimat3/storage 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -15,8 +15,9 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
   wrap it in its own `action()` with its own policy. See `docs/architecture/17-uploads.md`.
 
 - **Every byte ceiling and every TTL is screened where it is DECLARED, through core's
-  `finiteCount` and nothing else** — `uploadPolicy({ maxBytes })`, both drivers' `maxPutBytes`,
-  `createUploadGrant({ expiresInMs })`, `buildSignedUrl` and the s3 presign TTL. No private copy:
+  `finiteCount` and nothing else** — `uploadPolicy({ maxBytes })`, every driver's `maxPutBytes`
+  and `maxGetBytes`, variant `width`/`height`, `grantUpload({ expiresInMs })`, `buildSignedUrl`
+  and the s3 presign TTL. No private copy:
   `size > NaN` is false, so an unscreened `NaN` ceiling stops deciding anything. Variant `quality`
   is core's `assertFiniteImageQuality`, not a second screen.
 - **The default is taken on `undefined` and on nothing else** — `x === undefined ? D : x`, never
@@ -37,14 +38,24 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 
 | File | Owns |
 |---|---|
-| `driver.ts` | `StorageDriver` contract (8 methods) + 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-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` (`driver-local.ts`), the one rule both share |
-| `driver-s3.ts` | `Bun.S3Client`, built lazily (import must never open a socket) |
+| `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-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 |
 | `upload.ts` | magic-byte sniff + size/allowlist/checksum policy |
+| `iso-bmff.ts` | the `ftyp` MAJOR BRAND → media type (AVIF, HEIC, MOV, M4A, MP4, 3GP) |
 | `image.ts` | deterministic variant keys; byte path over core's pipeline (png/jpeg encode only) |
 | | `VARIANT_FORMATS` — what a variant KEY can carry — and NOT `IMAGE_FORMATS`, which is core's and means what core can PROBE. See below |
 | | `variantKey` is the cache identity `@ultimat3/cli`'s `/media/*` route looks a variant up by — derived, never stored, so a request that misses transforms once and every later one is a disk read |
@@ -60,6 +71,32 @@ bun run typecheck
 ```
 
 Gotchas:
+- **The local disk refuses a key that is another key's path, and that is pinned, not fixed**
+  (`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. 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
+  in which the sidecar may not describe the bytes: `get`/`stat`/`copy` re-check against the bytes,
+  `list` reports no type and `etag: ''`. A fresh key is absent until its bytes land.
+  `driver-local-crash.test.ts` dies at every step through `WriteSteps`. Writers and `get()` of one
+  key also queue in-process (`keyedQueue`) — unqueued, two puts interleaved 3/3.
+- **A refused write is `X_STORAGE_PUT_FAILED` and a refused read `X_STORAGE_READ_FAILED`**, on
+  local and s3 (both were bare throws); a 404 mid-read stays `X_STORAGE_NOT_FOUND`; `assertPutOptions` holds `metadata`/`cacheControl`/`contentType` to their types on
+  all three drivers before a byte moves.
+- **`get()` has a ceiling on every disk** (`maxGetBytes`, default `maxPutBytes`), decided on the
+  disk's own size before a byte is read. `promoteAttachment` REQUIRES the policy and measures with
+  `stat()`, which is a REQUIRED driver method — on s3 it is the first measurement of a direct upload.
+- **`lastModified` is optional — absent when the provider sent none**, never epoch 0 and never an
+  invalid `Date`. `sweepOrphans` spares an object with no proven age.
+- **The base PATH is inside the signature** (`SIGNED_URL_VERSION` `v2`): every local disk shares
+  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`): 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
@@ -74,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`
@@ -160,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`,
@@ -196,11 +226,11 @@ 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
-  `URIError` `decodeURIComponent` raises. Same shape as `@ultimat3/auth`'s `decodeCookieValue`.
+  `URIError` `decodeURIComponent` raises. Same shape as `@ultimat3/core`'s `readCookie`.
 - `acceptSignedUpload` refuses a URL signed with **no** content type (`unconstrained`). `grantUpload`
   always sets one, so such a URL is hand-rolled, and trusting the uploader's header instead is the
   only other option.
@@ -214,12 +244,10 @@ Gotchas:
   happens to be named `local`. An explicit `baseUrl` on `localDriver` outranks the registration
   (the operator saying where the route is mounted); an unregistered driver still mints under
   `local`. One driver instance under two disk names is refused at `defineStorage`
-  (`X_CONFIG_INVALID`) — it could only mint under one of them. Before that, the base was stated
-  twice (`/_storage/local` in the driver, `/_storage` in `verifySignedUrl`'s default) and NO
-  genuine URL verified at all: the key parsed as `local/<key>`. `@ultimat3/cli`'s
+  (`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
@@ -233,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,71 @@ 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)
+under `<root>/.meta/.tmp/` and then: renames the marker to `.meta/<key>.json.pending`, renames the
+sidecar, renames the bytes, removes the marker. What a reader sees if the process dies:
+
+| Died before | Fresh key | Overwrite |
+|---|---|---|
+| the marker or the sidecar rename | absent | the previous object, whole |
+| the bytes rename | absent (a sidecar alone is no object) | the previous BYTES; `get`/`stat` answer `application/octet-stream` and the bytes' own etag, `list` no type and `etag: ''` — never the new type |
+| clearing the marker | the new object to `get`/`stat` (re-checked against the bytes); `list` reports it untyped until the next put | same |
+
+No row serves a content type or an etag the bytes were not checked against. A marker that
+cannot be cleared after the renames landed is not a failed put — the object is committed and the
+last row is what it leaves. `stat()`, `list()` and a copy's source read queue behind the key's
+writer exactly as `get()` does. Writers and `get()` of
+ONE key are also serialised inside a process, so two concurrent puts cannot interleave; across
+processes the marker is what covers the window. `stream()` hands back bytes with no metadata and
+checks nothing. The layout is otherwise unchanged — an existing root needs no migration.
+
+**A refused write is coded.** `EACCES`, `ENOSPC`, `EROFS` or a root that is a file on the local
+disk, and a provider's refused PUT on s3, are `X_STORAGE_PUT_FAILED` from `put()` and `copy()`,
+with the errno or provider code in the cause. `put()` options are held to their types first
+(`assertPutOptions`: string `contentType`/`cacheControl`, a plain object of strings for
+`metadata`, `X_INVARIANT` otherwise) on all three drivers. A refused READ is `X_STORAGE_READ_FAILED` the same
+way. No driver method leaves with a bare throw for a wrong-typed argument either: a key that is not
+a string is `X_STORAGE_PATH_UNSAFE`, a body that is not bytes, a `Blob` or a stream and a
+non-string `list()` prefix or cursor are `X_INVARIANT` (`driver-read-failed.test.ts` sweeps every
+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 — 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
+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. 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
@@ -86,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 —
@@ -100,6 +183,42 @@ is the architecture and not an optimisation — see the round trip below. Raise
 for a disk that really does write large objects server-side, and remember S3 caps a single PUT at
 5GB whatever you set.
 
+**`get()` buffers too, so it has the same ceiling**: `maxGetBytes`, on all three drivers,
+defaulting to that disk's `maxPutBytes`. An object past it is `X_STORAGE_TOO_LARGE` — decided on
+the disk's own size (a HEAD on s3) before a byte is read — and is read with `stream()`. It exists
+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
@@ -123,7 +242,9 @@ it, `put('.meta/a/b.json', …)` overwrote the recorded content type of `a/b` an
 that object answered attacker HTML from the app's own origin. No sanitising — a key that needed
 fixing was built wrong.
 `scopedKey('org-1', 'avatars', 'a.png')` is `org/org-1/avatars/a.png`; guard every
-client-supplied key with `isWithinOrg(key, ctx.actor.orgId)`. A surface that serves objects pairs
+client-supplied key with `isWithinOrg(key, ctx.actor.orgId)` — a predicate that never throws: an
+org id that cannot be one (empty, or carrying a separator) contains nothing, so an actor with no
+org claim is `false` and not an `X_STORAGE_PATH_UNSAFE` blaming the key. A surface that serves objects pairs
 it with `isTenantScoped(key)`: only a key already inside `org/` is another tenant's to refuse, so
 `disk().put('brand/logo.png', …)` stays reachable while `org/org-2/…` never is. `accept.ts` asks
 the pair too. `isTenantScoped` folds case (`Org/`, `ORG/`) and `isWithinOrg` does not, so a
@@ -132,9 +253,17 @@ case-variant prefix — one directory, not two, on APFS or NTFS — is refused r
 ## Signed URLs
 
 The HMAC covers the **constraints**, not just the key —
-`v1 \n METHOD \n key \n expiresAt \n maxBytes \n contentType`.
+`v2 \n basePath \n METHOD \n key \n expiresAt \n maxBytes \n contentType`.
 A client that edits `?x-max=` invalidates the signature — it cannot widen what it was granted.
 
+`basePath` is the disk: the PATH of the base the URL was minted under (`/_storage/<registered
+name>`). Every local disk signs with the one `STORAGE_SIGNING_SECRET`, so without it a URL for
+`uploads/<key>` verified on `private/<key>` with only the path segment edited. The origin is not
+signed — the route that verifies is handed a path — and an absolute `baseUrl`
+(`https://cdn.example.com/_storage/local`) is compared by its pathname (`signedUrlBasePath`), where
+it used to make every URL minted under it `malformed`. `canonicalRequest` and `signConstraints`
+take the base path as their last argument.
+
 The HMAC key is `signingSecret`, else `STORAGE_SIGNING_SECRET`, else the shipped
 `DEV_SIGNING_SECRET` — and **only in `development` or `test`**, read with a fallback of `production`: a process that names no environment at all (`ULTIMATE_ENV` and `NODE_ENV` both unset) is refused like a production one, `As of 2026-09-23`. Anywhere else `localDriver` refuses
 to construct (`X_ENV_MISSING`) unless one of those two is set to something that is not the shipped
@@ -161,10 +290,20 @@ it on every grant, so refusing would break every s3 upload an app mints.
 
 `Content-Type` is attacker-controlled. A `.png` that is really an HTML document is stored XSS
 the moment a surface serves it back with the declared type. `validateUpload()` reads the magic
-bytes (PNG, JPEG, GIF, WebP, PDF, ZIP/OOXML, SVG, MP4, HTML, plain text) and rejects any
-payload whose bytes contradict the declaration. Checks run cheapest-first: key → size →
+bytes (PNG, JPEG, GIF, WebP, PDF, ZIP/OOXML, SVG, the ISO-BMFF family, HTML, plain text) and
+rejects any payload whose bytes contradict the declaration. Checks run cheapest-first: key → size →
 allowlist → sniff → checksum.
 
+Every ISO base media file opens with the same `ftyp` box, so the box alone says "container" and
+the **major brand** after it decides (`iso-bmff.ts`): `avif`/`avis` → `image/avif`, `heic`/`heix`…
+→ `image/heic`, `qt  ` → `video/quicktime`, `M4A `/`M4B ` → `audio/mp4`, `3gp*` → `video/3gpp`,
+anything else → `video/mp4`. Two brands name only a container and stand in as `application/zip`
+does for OOXML: `video/mp4` for a declared `audio/mp4` (an audio-only MP4 carries `isom`), and
+`image/heif` (`mif1`) for `image/heic` and `image/avif`. `audio/x-m4a` and `video/x-m4v` — what a
+browser reports for a picked file — normalise to `audio/mp4` and `video/mp4`, and
+`uploadPolicy({ allowedContentTypes })` normalises its list the same way, so an alias in an
+allowlist names the type it means.
+
 `validateUpload({ key, declaredContentType, bytes }, uploadPolicy({ maxBytes: 5e6 }))`
 
 ## The direct-upload round trip
@@ -226,7 +365,7 @@ An upload happens **before** the row it belongs to exists, so it lands at
 | `pendingKey(orgId, uploadName(id, filename))` | `org/o1/pending/u-1.png` |
 | `quarantineKey(orgId, name)` | `org/o1/pending/quarantine/u-1.png` |
 | `attachmentKey(orgId, { entity, id, field }, name)` | `org/o1/post/p-1/cover/u-1.png` |
-| `promoteAttachment({ disk, key, orgId, target })` | `copy` then `delete` — never the reverse. The key must be a **pending** one (`isPendingKey`): an attached key a client sent back is another row's file, and moving it would delete the victim's copy (`X_STORAGE_NOT_PENDING`) |
+| `promoteAttachment({ disk, key, orgId, target, policy })` | `stat`, `copy`, then `delete` — never the reverse. **`policy` is required**: the object is measured here (`stat().size` over `policy.maxBytes` is `X_STORAGE_TOO_LARGE`, and it stays under `pending/` for the sweep), because an s3 presign bounds no size. A retry after the source is gone answers the already-attached object instead of `X_STORAGE_NOT_FOUND`. The key must be a **pending** one (`isPendingKey`): an attached key a client sent back is another row's file, and moving it would delete the victim's copy (`X_STORAGE_NOT_PENDING`) |
 | `releaseQuarantine({ disk, key, orgId })` | quarantine → pending; returns the released key |
 | `sweepOrphans({ disk, orgId, olderThanMs })` | `{ deleted, failed }` for stale `pending/` keys. `olderThanMs` is a whole number of 0 or more, refused otherwise (`X_INVARIANT`) — `NaN` read as "everything is old enough" and deleted an upload made a moment ago |
 
@@ -266,7 +405,7 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_DISK_UNKNOWN` | `disk(name)` is not in `storage.disks`; cause lists the real ones |
 | `X_STORAGE_NOT_FOUND` | `get`/`stream` on a key that does not exist |
 | `X_STORAGE_PATH_UNSAFE` | traversal, absolute key, backslash, NUL, `%2e`, empty segment |
-| `X_STORAGE_TOO_LARGE` | payload over the policy `maxBytes`, or over a disk's `maxPutBytes` |
+| `X_STORAGE_TOO_LARGE` | payload over the policy `maxBytes` (at validation, or measured by `promoteAttachment`), or over a disk's `maxPutBytes` / `maxGetBytes` |
 | `X_STORAGE_TYPE_REJECTED` | declared type off the allowlist, or contradicted by magic bytes |
 | `X_STORAGE_CHECKSUM_MISMATCH` | supplied base64 SHA-256 does not describe the bytes |
 | `X_STORAGE_URL_INVALID` | a signed request that does not match what was signed — edited constraint, wrong base, wrong method, contradicting `Content-Type` |
@@ -277,7 +416,11 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_LIST_FAILED` | the disk REFUSED a listing — denied `s3:ListBucket`, a throttle, an unreadable root. An **empty** disk is still not an error |
 | `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_NOT_IMPLEMENTED` | S3 user metadata / cache-control; `serverSideEncryption` on either driver |
+| `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 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 |
@@ -296,6 +439,13 @@ a job boundary the class is gone and the `code` is what survives — match on th
 `variantKey()`, `srcsetDescriptors()`, `fitDimensions()` are pure — `@ultimat3/seo` builds
 `srcset` from them without decoding a byte.
 
+A variant key is the WHOLE source key plus the transform: `photos/hero.png` at width 640 is
+`photos/hero.png@w640.webp`. The source extension stays in, so `hero.png` and `hero.jpg` are two
+cache identities — it was cut, and both minted `photos/hero@w640.webp`. `width` and `height` are
+whole numbers of at least 1 on `variantKey` and `fitDimensions` (`X_INVARIANT` otherwise — no
+`wNaN`, no `w1.5`). `fitDimensions` never answers a zero edge (1000×1 at width 100 is 100×1) and
+never upscales except under `fit: 'cover'`, which is the exact box asked for.
+
 **`VARIANT_FORMATS` / `VariantFormat` are what a variant KEY can carry, `As of 2026-08`** —
 `avif`, `webp`, `jpeg`, `png` — and this package exports no `IMAGE_FORMATS` and no `ImageFormat`. Those two names are
 `@ultimat3/core`'s, over the six formats it can PROBE (`png`, `jpeg`, `webp`, `avif`, `gif`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "23.0.0",
+  "version": "25.0.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": "23.0.0"
+    "@ultimat3/core": "25.0.0"
   }
 }

package/src/accept.ts

@@ -113,12 +113,9 @@ async function constraintsFor(
   // The PAIR is the question "does this key belong to somebody else?". `isWithinOrg` alone
   // answered `false` for every un-scoped key, so an app's own `brand/logo.png` was unreachable
   // through a URL it had just signed — `path.ts` says so and `dev-storage.ts` already asks it this
-  // way. An actor with no org is inside no org, so every tenant-scoped key is somebody else's;
-  // checked here because `isWithinOrg` reads an empty org as a malformed key and would blame the
-  // URL for the actor's missing claim.
-  const orgId = input.orgId;
-  if (isTenantScoped(constraints.key) && (orgId === '' || !isWithinOrg(constraints.key, orgId))) {
-    throw orgMismatch(constraints.key, orgId);
+  // way. An actor with no org is inside no org, and `isWithinOrg` answers exactly that.
+  if (isTenantScoped(constraints.key) && !isWithinOrg(constraints.key, input.orgId)) {
+    throw orgMismatch(constraints.key, input.orgId);
   }
   return constraints;
 }

package/src/attachment.ts

@@ -5,10 +5,11 @@
 // so the tenant prefix is a construction, not a check somebody remembered to write.
 
 import type { Clock } from '@ultimat3/core';
-import { finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
-import type { ListPage, StorageDriver, StorageListEntry, StorageObject } from './driver';
-import { notPending, orgMismatch, quarantined } from './errors';
+import { assert, finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
+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';
 
 /** The one segment an unattached upload lives under. `sweepOrphans` reads only this prefix. */
 export const PENDING_SEGMENT = 'pending';
@@ -123,13 +124,27 @@ export interface PromoteAttachmentInput {
   readonly key: string;
   readonly orgId: string;
   readonly target: AttachmentTarget;
+  /**
+   * The policy the upload was GRANTED under — required, never defaulted. On a bucket-backed disk
+   * the presigned PUT carries no size, so `policy.maxBytes` bound nothing until this call measured
+   * the object; a default here would silently replace an app's own ceiling with the framework's.
+   */
+  readonly policy: UploadPolicy;
 }
 
 /**
  * Move a pending upload onto the row that now exists. Copy first, delete second: a delete that
  * ran first would lose the bytes on a failed write, and the sweep would have collected them
- * anyway. Re-promoting an already-promoted key is `X_STORAGE_NOT_FOUND` from the copy, never a
- * silent no-op that leaves the caller believing a file is attached.
+ * anyway.
+ *
+ * MEASURED before it moves: `stat().size` over `policy.maxBytes` is `X_STORAGE_TOO_LARGE`, and the
+ * object stays under `pending/` for `sweepOrphans` — never at a key a row points to. `stat` and
+ * not `get`: this is the call that learns the size, so it cannot be one that buffers it.
+ *
+ * Idempotent across a retry: a source that is gone with the destination already there answers the
+ * destination. Promotion is copy-then-delete inside a request whose row write can still roll back,
+ * and the retry used to raise `X_STORAGE_NOT_FOUND` for a file sitting exactly where it belonged.
+ * A source that is gone with NO destination is still `X_STORAGE_NOT_FOUND`.
  *
  * The copy is `disk.copy`, not `get` + `put`: promotion used to download the whole object into
  * this process and upload it again, so attaching a 500MB file moved a gigabyte through the pod
@@ -141,10 +156,27 @@ export async function promoteAttachment(input: PromoteAttachmentInput): Promise<
   // copy-then-delete below would move that row's file here and delete theirs.
   if (!isPendingKey(input.key, input.orgId)) throw notPending(input.key, input.orgId);
   if (isQuarantinedKey(input.key, input.orgId)) throw quarantined(input.key, input.orgId);
+  // The type says required; an untyped caller upgrading from the four-field call does not read
+  // types, and `input.policy.maxBytes` on `undefined` is a bare `TypeError` two lines down.
+  assert(
+    typeof input.policy?.maxBytes === 'number',
+    'promoteAttachment was called with no policy, so nothing bounds the size of the upload it attaches',
+    'promoteAttachment({ disk, key, orgId, target, policy: uploadPolicy({ maxBytes }) }) — the policy the upload was granted under',
+  );
+  const disk = input.disk;
   const name = input.key.slice(input.key.lastIndexOf('/') + 1);
   const attached = attachmentKey(input.orgId, input.target, name);
-  const object = await input.disk.copy(input.key, attached);
-  await input.disk.delete(input.key);
+  const pending = await disk.stat(input.key);
+  if (pending === undefined) {
+    const already = await disk.stat(attached);
+    if (already !== undefined) return already;
+    throw objectNotFound(disk.name, input.key);
+  }
+  if (pending.size > input.policy.maxBytes) {
+    throw tooLarge(input.key, pending.size, input.policy.maxBytes);
+  }
+  const object = await disk.copy(input.key, attached);
+  await disk.delete(input.key);
   return object;
 }
 
@@ -197,14 +229,12 @@ 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) {
-      if (object.lastModified.getTime() > cutoff) continue;
+    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;
       try {
         await input.disk.delete(object.key);
@@ -213,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 };
 }