@ultimat3/storage 22.15.0 → 24.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,12 +38,19 @@ 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` 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-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 |
@@ -58,6 +66,33 @@ 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. `driver-contract.test.ts` runs the claim on all
+  three disks.
+- **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`), so two sources differing
+  only by extension are 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
@@ -187,12 +222,18 @@ Gotchas:
   whole path exists to prevent. That is why it derives the box itself and asks core for
   `fit: 'cover'` — core's `contain` letterboxes to the requested box, this API fits inside it.
 - Bun's S3 flag is `virtualHostedStyle`; our `forcePathStyle` is its inverse.
+- **No `region` signs for `auto`.** R2 wants that; AWS and a gateway that checks the scope answer
+  `AuthorizationHeaderMalformed … expecting "<region>"`. `put`/`copy`/`list`/`delete` ask
+  `regionMismatch()` BEFORE their own verdict, so the code is `X_CONFIG_INVALID` and the fix is the
+  region — never `X_STORAGE_LIST_FAILED` with a fix about `s3:ListBucket`. The captured region is
+  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
   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.
@@ -206,9 +247,7 @@ 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.**

package/README.md

@@ -16,14 +16,44 @@ defineStorage({
 await disk('media').put(scopedKey(orgId, 'avatars', 'a.png'), bytes, { contentType: 'image/png' });
 ```
 
-Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs no MinIO.
+Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs no S3 server.
 
 ## Drivers
 
 | Driver | Backing | For | Signed URLs |
 |---|---|---|---|
 | `localDriver` | `Bun.file`/`Bun.write`, one root dir | dev, tests, single-node | HMAC + dev route |
-| `s3Driver` | `Bun.s3` | prod: MinIO, R2, AWS | provider presign |
+| `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 |
+
+`memoryDriver()` 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
+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';
+
+// 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();
+beforeEach(() => {
+  sessions = memoryDriver();
+  defineStorage({ disks: { sessions } });
+});
+afterEach(() => resetStorage());
+
+await disk('sessions').put('org/o1/session.json', new TextEncoder().encode('{"sealed":"x1.…"}'));
+const stored = [...sessions.objects().values()].map((bytes) => new TextDecoder().decode(bytes));
+```
+
+Server-side only, like both other drivers: nothing an island imports reaches it.
+
+`region` is what requests are signed for; unset, that is `auto`. An endpoint that expects another
+region refuses the first write, list or delete with `X_CONFIG_INVALID`, and the fix names the
+`S3_REGION` to set.
 
 `copy(from, to)` is on the contract so a promotion is not a download-and-reupload:
 `promoteAttachment` used to `get()` the whole object into the app and `put()` it back, a gigabyte
@@ -39,6 +69,51 @@ sidecar so `get()`/`list()` round-trip everything `put()` was handed; sidecars n
 `list()`. `s3Driver` cannot: it refuses `cacheControl`/`metadata` on `put()` (`X_NOT_IMPLEMENTED`,
 Bun exposes no header hook yet).
 
+**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.** 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.
+
+`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.
+
 **`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
 value would cost one `HeadObject` per row, which is what `list()` exists to avoid. It used to
@@ -70,6 +145,12 @@ 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.
+
 ## Server-side encryption, storage classes, lifecycle
 
 `PutOptions.serverSideEncryption` exists so the gap is visible **at the type level**, and every
@@ -93,7 +174,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
@@ -102,9 +185,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
@@ -131,10 +222,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
@@ -196,7 +297,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 |
 
@@ -236,7 +337,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` |
@@ -247,6 +348,9 @@ 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_STORAGE_PUT_FAILED` | the disk REFUSED a `put()`/`copy()` — `EACCES`, `ENOSPC`, `EROFS`, a provider's refused PUT |
+| `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_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 |
@@ -266,6 +370,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": "22.15.0",
+  "version": "24.0.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0"
+    "@ultimat3/core": "24.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 { assert, finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
 import type { ListPage, StorageDriver, StorageListEntry, StorageObject } from './driver';
-import { notPending, orgMismatch, quarantined } from './errors';
+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;
 }
 
@@ -204,7 +236,8 @@ export async function sweepOrphans(input: SweepOrphansInput): Promise<SweepResul
       ...(cursor === undefined ? {} : { cursor }),
     });
     for (const object of page.objects) {
-      if (object.lastModified.getTime() > cutoff) continue;
+      // 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);

package/src/driver-local-read.ts

@@ -0,0 +1,104 @@
+// Single responsibility: what the local disk KNOWS about one object — its bytes file, its sidecar,
+// and the pending marker that says whether the two can be trusted as a pair. A write that died
+// between its renames leaves a sidecar describing bytes that never landed; this is where that is
+// read as "type unknown" instead of served as the truth.
+
+import { renderFixShellArg, stringField } from '@ultimat3/core';
+import type { StorageListEntry } from './driver';
+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> {
+  const file = Bun.file(`${root}/${sidecarPathOf(key)}`);
+  if (!(await file.exists())) return undefined;
+  try {
+    const raw: unknown = await file.json();
+    return parseSidecar(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The etag a write in flight — or one that died — announced before it moved anything. */
+async function pendingEtag(root: string, key: string): Promise<string | undefined> {
+  const file = Bun.file(`${root}/${pendingPathOf(key)}`);
+  if (!(await file.exists())) return undefined;
+  return (await file.text().catch(() => '')).trim();
+}
+
+/**
+ * A read the OS refused, coded: `EACCES`, `EIO`, a directory where the bytes should be. A file
+ * that is simply gone — deleted between the `exists()` and the read — is "not found", as it
+ * would have been one call earlier.
+ */
+const refusedRead =
+  (root: string, key: string) =>
+  (error: unknown): never => {
+    if (isStorageError(error)) throw error;
+    throw stringField(error, 'code') === 'ENOENT'
+      ? objectNotFound('local', key)
+      : readFailed(
+          'local',
+          key,
+          error,
+          `ls -l ${renderFixShellArg(`${root}/${key}`, '<the object file>')}`,
+        );
+  };
+
+/** The whole object, buffered — `get()`'s one read. */
+export async function readObjectBytes(root: string, key: string): Promise<Uint8Array> {
+  return Bun.file(`${root}/${key}`)
+    .arrayBuffer()
+    .then((buffer) => new Uint8Array(buffer), refusedRead(root, key));
+}
+
+/** `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> {
+  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 hasher.digest('hex').slice(0, 32);
+}
+
+/**
+ * One object's facts, or `undefined` when there are no bytes at the key — the bytes file is what
+ * makes an object exist, so a sidecar alone (a fresh write that died early) is nothing at all.
+ *
+ * The sidecar is TRUSTED unless the pending marker names its etag: that is the one state in which
+ * the sidecar is the new write's and the bytes may still be the old object's. Then, and for an
+ * object with no sidecar, the answer depends on `trueEtag`:
+ * - absent (a listing, which never reads bytes): no content type, `etag: ''` — "cannot know";
+ * - given: the bytes decide. A match keeps the sidecar; a mismatch drops every field it claimed
+ *   and reports the bytes' own etag.
+ *
+ * No path here answers a type or an etag the bytes were not checked against while in doubt.
+ */
+export async function headObject(
+  root: string,
+  key: string,
+  trueEtag?: () => string | Promise<string>,
+): Promise<StorageListEntry | undefined> {
+  const file = Bun.file(`${root}/${key}`);
+  if (!(await file.exists())) return undefined;
+  const recorded = await readSidecar(root, key);
+  const inDoubt = recorded !== undefined && (await pendingEtag(root, key)) === recorded.etag;
+  let sidecar = recorded;
+  let etag = recorded?.etag ?? '';
+  if (recorded === undefined || inDoubt) {
+    etag = trueEtag === undefined ? '' : await trueEtag();
+    if (recorded?.etag !== etag) sidecar = undefined;
+  }
+  return {
+    key,
+    size: file.size,
+    etag,
+    lastModified: new Date(file.lastModified),
+    ...(sidecar?.contentType === undefined ? {} : { contentType: sidecar.contentType }),
+    ...(sidecar?.cacheControl === undefined ? {} : { cacheControl: sidecar.cacheControl }),
+    ...(sidecar?.metadata === undefined ? {} : { metadata: sidecar.metadata }),
+  };
+}

package/src/driver-local-sidecar.ts

@@ -0,0 +1,38 @@
+// 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.
+
+export interface Sidecar {
+  readonly contentType: string;
+  readonly etag: string;
+  readonly cacheControl?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+
+// `!Array.isArray` is the load-bearing clause, matching `isPlainObject` in
+// `@ultimat3/schema`'s `builder.ts`: `typeof [] === 'object'` and every value of `['a','b']` is a
+// string, so an array in the `metadata` slot was handed back through `head()`/`get()` as object
+// metadata — against a `Record<string, string>` every reader downstream is typed on.
+const isStringRecord = (value: unknown): value is Readonly<Record<string, string>> =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.values(value as Record<string, unknown>).every((entry) => typeof entry === 'string');
+
+export function parseSidecar(raw: unknown): Sidecar | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const record = raw as Record<string, unknown>;
+  const contentType = record['contentType'];
+  const etag = record['etag'];
+  if (typeof contentType !== 'string' || typeof etag !== 'string') return undefined;
+  // `put()` writes cacheControl/metadata into the same sidecar — dropping them here silently
+  // truncated what was just written, even though `Sidecar` itself declares both.
+  const cacheControl = record['cacheControl'];
+  const metadata = record['metadata'];
+  return {
+    contentType,
+    etag,
+    ...(typeof cacheControl === 'string' ? { cacheControl } : {}),
+    ...(isStringRecord(metadata) ? { metadata } : {}),
+  };
+}