@ultimat3/storage 29.4.0 → 30.1.0

package/CLAUDE.md

@@ -38,9 +38,15 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 
 | File | Owns |
 |---|---|
-| `driver.ts` | `StorageDriver` contract (9 methods; `registerAs`/`verifySigned`/`retentionOf` optional), `assertPutOptions`, + bounded `toBytes`/`sha256Base64`/`etagOf` |
+| `driver.ts` | `StorageDriver` contract (11 methods; `registerAs`/`verifySigned`/`retentionOf` optional), `assertPutOptions`, + bounded `toBytes`/`sha256Base64`/`etagOf` |
+| `byte-pump.ts` / `put-stream.ts` | the one counting read, `put()`'s and `putStream`'s; the `putStream` screen and limit |
+| `multipart.ts` / `driver-s3-multipart*.ts` / `driver-s3-put-stream.ts` | part arithmetic + `MultipartCapability`; the six signed calls + s3's capability; the pump |
+| `grant-multipart.ts` / `upload-client-multipart.ts` / `accept-part.ts` / `multipart-staged.ts` | uploads in parts: server calls, browser, local part PUT, local/memory sessions |
+| `expire.ts` | `expireObjects`, `abortStaleUploads`, `objectPurgeTarget` |
+| `driver-local-stream.ts` / `driver-s3-sse.ts` / `errors-stream.ts` | the staged local stream; the s3 SSE refusal; the stream codes |
+| `driver-s3-settle.ts` | a lost Complete/PUT answer, settled by a stat (size + S3's etag of the bytes sent: MD5, or MD5-of-part-MD5s `-N`), then for multipart by an abort (204 = was open, nothing stored; 404 = completed, stat again). Neither settles: `X_STORAGE_WRITE_OUTCOME_UNKNOWN`, never `X_STORAGE_PUT_FAILED`. Plain `put()` settles the same way (`settleLostPut`); `isAnswered` (coded, or Bun's `S3Error`) is what counts as the provider answering |
 | `range.ts` | `get(key, { range })`: screen + `servedRange` (`errors-range.ts`); s3's one-GET read is `driver-s3-range.ts` |
-| `driver-local.ts` | dev default over `Bun.file`, `.meta/` sidecars, `Bun.Glob` listing |
+| `driver-local.ts` | dev default over `Bun.file`, `.meta/` sidecars; listing is `driver-local-list.ts` (`Bun.Glob`, cursor, `listFailed`), removal `driver-local-remove.ts` (a refused unlink vs one already gone) |
 | `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 |
@@ -51,6 +57,7 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 | `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` |
+| `driver-s3-copy.ts` | `copy(…, { ifMatch })`: a signed CopyObject |
 | `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 |
@@ -60,11 +67,14 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 | `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 |
+| `image-warm.ts` | `warmVariants`: a stored image's variants written ahead of `/media`, under its keys, the revision off the bytes read; core's spec, so a warmed variant is the one a miss would store |
 | `storage.ts` | `defineStorage` + module-level `storage()` / `disk()` |
 | `grant.ts` | `grantUpload` — the ONE way a presigned PUT is minted; the client never names a key |
 | `accept.ts` | `acceptSignedUpload` / `readSignedObject` — the two decisions a `/_storage` route is made of |
-| `attachment.ts` | `pending/` → row promotion, the `quarantine/` segment, and `sweepOrphans` |
+| `attachment.ts` | `pending/` → row promotion, the `quarantine/` segment, `sweepOrphans` and `deleteVariants` |
+| `errors-sniff.ts` | the two `X_STORAGE_TYPE_REJECTED` refusals only a bounded sniff reaches: too much leading whitespace, XML past the window |
 | `upload-client.ts` | the browser half: grant → PUT with progress → key. No `Bun.*`, no `node:` |
+| `subject-target.ts` | `storageSubjectTarget(disk, keysOf)` — structural `SubjectTarget`: the app names the keys, export lists, erase deletes |
 
 ```bash
 bun test                      # from packages/storage
@@ -109,11 +119,7 @@ Gotchas:
   Without `dot`, dot-prefixed keys were missing from the listing while `put`/`get` handled them —
   and `sweepOrphans` pages through `list()`. Pinned in `driver-parity.test.ts`.
 - **A `list({ limit })` is a positive integer or a refusal** — `resolveListLimit` at the
-  `ListOptions` seam, so both disks answer one way. `limit: 0` used to slice `[0, 0)` on the local
-  disk and then drop its own `truncated` flag (`truncated && last !== undefined`, with an empty
-  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.
+  `ListOptions` seam, so both disks answer one way. Core's `assert` (`X_INVARIANT`).
 - **`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
@@ -136,13 +142,11 @@ Gotchas:
   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`
-  covers method, expiry and type — so on the production disk the client PUTs straight into the
-  bucket and nothing between the grant and the object holds the ceiling. That belongs to a bucket
-  rule or a post-upload `object.size` check, neither of which is a driver's; `SignedUrlOptions`
-  says so and `driver-parity.test.ts` pins both halves.
+- **A grant binds its size on every disk** (`As of 2026-11-02`). `grantUpload` requires `request.size` and passes `contentLength`; `s3Driver` signs `content-length` through core's `presignAwsUrl`, because Bun's presign signs `host` alone, so any other length is a 403 (`driver-s3.live.test.ts`). Local and memory hold it as the `x-max` ceiling, so a shorter body passes there: `driver-parity.test.ts` pins it. `maxBytes` with no `contentLength` on s3 is `X_STORAGE_UPLOAD_SIZE_UNDECLARED`. The content type stays unsigned.
+- **`putStream` on s3 is signed multipart, never `S3File.writer()`.** Measured on Bun 1.4.4: `end(error)` COMPLETES the upload, so an overrun would replace the object, and the writer cannot send `x-amz-meta-*`. One part at a time; every exit but the Complete aborts; a Complete can fail with 200 and an `<Error>` body.
+- **`promoteAttachment` sniffs a head window** (`validateStoredHead`, 64 KiB), then ties it to the
+  copy: `ifMatch`, then size and etag. Never refuse on etag alone: SSE-KMS mints one per copy.
+- **`/media`'s variant key names its source's revision and format.** No `revision`: the old key.
 - **`delete()` is idempotent for an ABSENT key and for nothing else.** Both drivers used to end in
   `.catch(() => undefined)`, so a denied `s3:DeleteObject`, a `SlowDown`, an expired credential and
   a read-only mount all resolved as success — and `sweepOrphans` returned them as deleted, which
@@ -160,7 +164,7 @@ Gotchas:
 - **`serverSideEncryption` is declared and refused by BOTH drivers.** Bun exposes `acl`,
   `storageClass` and `type` and nothing for `x-amz-server-side-encryption*`, and a POSIX file is
   not encrypted at all. Refusing on the dev disk too is deliberate: a `put()` that works in `x dev`
-  and throws in production is two rules. Lifecycle, storage classes and replication stay out
+  and throws in production is two rules. Bucket lifecycle (the app sweeps with `expire.ts`), storage classes and replication stay out
   entirely — bucket-side, terraform's, axiom 7.
 - **Quarantine is `pending/quarantine/`, INSIDE the pending prefix.** So `sweepOrphans` collects a
   never-scanned upload with no second prefix to walk, and `isPendingKey` stays true for it.
@@ -168,9 +172,7 @@ Gotchas:
   the app's scan verdict, and returns the ordinary pending key promotion accepts. Ultimate ships
   no scanner — axiom 8, and `application/zip` is an accepted OOXML container by design.
 - **`StorageListEntry` vs `StorageObject`.** A listing's `contentType` is optional; a `get()`'s is
-  not. `ListObjectsV2` returns no Content-Type, and the s3 driver used to invent
-  `application/octet-stream` while the local driver read the truth from its sidecar — two drivers
-  disagreeing about one object. The local `list()` now omits it too when there is no sidecar.
+  not. `ListObjectsV2` returns no Content-Type, and no driver invents one.
 - **`META_DIR` lives in `path.ts`, not in `driver-local.ts`.** The sidecar namespace overlapped the
   object namespace: `put('a/b', png)` writes `<root>/.meta/a/b.json`, and `.meta/a/b.json` was
   itself a legal key, so an uploader could rewrite another object's recorded `contentType` to
@@ -178,17 +180,7 @@ Gotchas:
   `assertSafeKey`, so it holds for S3 too — a key valid on one driver and refused on another is two
   key rules, and the reservation folds case — see above. The `list()` skip is not a second line of
   defence but the only one: the glob yields the sidecar tree.
-- **`localDriver` refuses to construct outside development without a usable signing secret**
-  (`X_ENV_MISSING`, borrowed from core). Usable means neither the `signingSecret` option nor
-  `STORAGE_SIGNING_SECRET` is missing, empty **or** the published `DEV_SIGNING_SECRET` — pasting
-  the literal into `app.config.ts` configures nothing, so it is refused exactly as its absence is.
-  `DEV_SIGNING_SECRET` is published in this repo, and `acceptSignedUpload` trusts a signed URL's
-  constraints over the app's `uploadPolicy` — so the fallback is a universal grant to mint any
-  `PUT`. Refused at construction, not at the first `signedUrl()`: a process that cannot sign safely
-  must not finish booting. The cause names the environment `resolveEnvironment()` resolved, which
-  may be `NODE_ENV`'s, never a variable the process did not set. `usesDevStorageSecret()` is the
-  `x doctor` predicate, mirroring core's `usesDevCursorSecret()`; it reads the env var, so a disk
-  handed an explicit `signingSecret` is outside its question.
+- **`localDriver` refuses to construct outside development without a usable signing secret** (`X_ENV_MISSING`, borrowed from core). Full rule: `docs/history/storage.md`.
 - **`localDriver({ env })` and `usesDevStorageSecret({ env })` are ONE question about ONE table**:
   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.
@@ -197,8 +189,8 @@ Gotchas:
   /_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`,
-  `isTenantScoped`/`isWithinOrg` and the driver's own `contentType`/`etag`; the `Response` is the
-  host's, exactly as `accept.ts`'s header says.
+  `isTenantScoped`/`isWithinOrg` and the driver's own `contentType`/`etag`; the `Response` is
+  `@ultimat3/http`'s `objectResponse`, structural over those fields, as `accept.ts`'s header says.
 - `acceptSignedUpload` still has no mounted route: the signing secret is closed over inside
   `localDriver` and no `StorageDriver` method exposes it, so a host cannot verify a signed PUT
   through the `Storage` seam it is handed. Serving reads needed none of it (policy decides, not a
@@ -237,19 +229,7 @@ Gotchas:
 - `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.
-- **The signed base is the disk's REGISTERED name, and it is stated once — on the driver.**
-  `defineStorage` tells each driver its registration key (`StorageDriver.registerAs`), the driver
-  rebases its URLs onto `signedUrlBaseFor(diskName)`, and `accept.ts` reads `disk.signedUrlBase`
-  rather than deriving a second one. Both halves used to derive it from `disk.name` — the DRIVER
-  kind — so they agreed with each other and disagreed with the mounted `/_storage/:disk/*key`
-  route, which resolves the segment through the registry: a disk registered as `uploads` minted
-  `/_storage/local/...` and 404'd its own signatures. Latent only because every disk in this repo
-  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. `@ultimat3/cli`'s
-  `STORAGE_BASE_PATH` is a third statement of the mount prefix and should import
-  `DEFAULT_SIGNED_URL_BASE` instead.
+- **The signed base is the disk's REGISTERED name, and it is stated once — on the driver.** Full rule: `docs/history/storage.md`.
 - **`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:

package/README.md

@@ -2,6 +2,8 @@
 
 Named disks. **Call sites name a disk, never a driver.**
 
+`bun add @ultimat3/storage` · guide: [Storage And Uploads](https://github.com/developerz-ai/ultimate/wiki/Storage-And-Uploads)
+
 ```ts
 import { defineStorage, disk, localDriver, s3Driver, scopedKey } from '@ultimat3/storage';
 
@@ -191,8 +193,22 @@ for a disk that really does write large objects server-side, and remember S3 cap
 **`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.
+because an object's size is not the server's to choose: a URL signed with no `contentLength` lands
+in a bucket unmeasured, so a later `get()` of it was heap growth the uploader picked.
+
+## Large objects — `streamRange(key, [first, last])` and `putStream(key, stream, { maxBytes })`
+
+`streamRange` reads no byte before `first`: s3 and local through `slice(...).stream()`, memory from
+its copy. Inclusive and clamped like `get`'s range, with no ceiling because nothing is buffered;
+past the end is `X_STORAGE_RANGE_UNSATISFIABLE`. `putStream` takes `contentType`, `cacheControl`,
+`metadata` and a REQUIRED `maxBytes` (`PutStreamOptions`). Past it the source is cancelled, nothing
+is stored and the key stays as it was (`X_STORAGE_TOO_LARGE`). `checksum`, `retention`, `legalHold`
+and `serverSideEncryption` need the bytes up front: the type omits them and an untyped caller gets
+`X_INVARIANT`. On s3 a body under one part is one signed PUT and past it a signed multipart upload,
+one part at a time (5 MiB or `maxBytes / 10000`), aborted on every exit but the Complete: Bun's
+`S3File.writer()` completes on `end(error)` and sends no `x-amz-meta-*`. Local stages under
+`.meta/.tmp/`, then runs `put()`'s commit steps. A driver outside this package reuses
+`assertPutStream`, `pumpBounded`, `streamLimit`, `assertStreamRange`, `streamedRange` and `signedByteBound`.
 
 ## Ranged reads — `get(key, { range: [first, last] })`
 
@@ -259,10 +275,19 @@ shipped driver refuses it (`X_NOT_IMPLEMENTED`) with the out-of-band command in
 `x-amz-server-side-encryption*`; a local disk writes plain files. A typed refusal an engineer
 meets at the call site beats a silent absence discovered during a security review.
 
-Encryption at rest is therefore a **bucket default**, and so are lifecycle rules, storage classes
-and cross-region replication: all four are bucket-side configuration and belong to terraform, not
-to the framework (axiom 7 — zero platform primitives). Ultimate half-building any of them would
-be a second place to look for the same setting.
+Encryption at rest is therefore a **bucket default**, and so are bucket lifecycle rules, storage
+classes and cross-region replication: all four are bucket-side configuration and belong to
+terraform, not to the framework (axiom 7 — zero platform primitives). Ultimate half-building any of
+them would be a second place to look for the same setting.
+
+What the app sweeps itself, on every disk, is `expire.ts` (`As of 2026-11-06`): the window is the
+app's and required at the call.
+
+| Call | Answers |
+|---|---|
+| `expireObjects({ disk, prefix, olderThanMs, keep?, clock? })` | `{ deleted, failed, spared }`. Undated is spared, a locked object is `failed`, never forced; an empty `prefix` is refused |
+| `abortStaleUploads({ disk, olderThanMs, prefix?, match? })` | `{ aborted, failed, spared }` over the disk's open upload sessions |
+| `objectPurgeTarget({ name, disk, prefix, match?, olderThanMs })` | `@ultimat3/jobs`' `PurgeTarget`, structurally: both sweeps as one target of the app's `purge()`. `match(key)` narrows both to one kind of file under every tenant (`org/<id>/imports/`) |
 
 ## Keys
 
@@ -313,10 +338,12 @@ a test fixture), or the guard answers about one process and the disk signs accor
 Verification is constant-time, checks the signature *before* the expiry (a forged URL never
 learns it was merely late), takes a `Clock` so tests freeze time, and returns
 `{ ok: false, reason }` rather than throwing — `malformed | unsafe-key | signature-mismatch |
-expired`. S3 presign covers method, expiry and content type but **not** `maxBytes`: S3 has no
-header for it, so a bucket-backed disk's ceiling is a bucket rule or a post-upload `object.size`
-check, never the signature. `s3Driver` does not refuse `maxBytes` either — `grantUpload` supplies
-it on every grant, so refusing would break every s3 upload an app mints.
+expired`. An S3 presign binds method and expiry, and `contentLength` where it is given: `s3Driver`
+then signs `content-length` with core's `presignAwsUrl`, so the provider refuses any other length
+(403, `driver-s3.live.test.ts`). Bun's presign, the path without one, signs `host` alone. Either way
+`contentType` is unsigned: it becomes `response-content-type`, which governs a GET, so a PUT's
+`Content-Type` is the uploader's, and the type is `promoteAttachment`'s sniff. `s3Driver` refuses
+`maxBytes` with no `contentLength` (`X_STORAGE_UPLOAD_SIZE_UNDECLARED`): it has no ceiling to sign.
 
 ## Uploads sniff the content type
 
@@ -338,6 +365,14 @@ allowlist names the type it means.
 
 `validateUpload({ key, declaredContentType, bytes }, uploadPolicy({ maxBytes: 5e6 }))`
 
+**The same rule over an object already on a disk:**
+`validateStoredHead({ key, declaredContentType, head, size }, policy)`, where `head` is
+`disk.get(key, { range: [0, SNIFF_WINDOW_BYTES - 1] })`'s bytes (64 KiB) and `size` the object's. No
+checksum, and no buffering of the object. It answers `{ key, contentType, size }`. A character cut at
+the window's end is not a bad sequence. An XML or `+xml` type over the window is refused, because XML
+runs a script anywhere in the document and only `validateUpload` reads all of it. On both paths, over
+`MAX_LEADING_WHITESPACE` (4,096 B) of leading whitespace is `X_STORAGE_TYPE_REJECTED`.
+
 ## The direct-upload round trip
 
 Three calls, one per hop. The **client never names the key** — it asks for a grant and is told
@@ -387,6 +422,26 @@ no bytes, and the signed `maxBytes` caps the body read. Then it calls `acceptSig
 policy built from the grant's own signed type and ceiling. The routes serve `definedStorage()`,
 the process's one registry, which is the app's `defineStorage` when it declared one (#524).
 
+## Uploads in parts — `grantMultipart`, `signPart`, `listParts`, `completeUpload`, `abortUpload`
+
+`As of 2026-11-06`. Resumable, and past S3's 5 GiB single PUT. Same policy gate as `grantUpload`
+(`decideGrant`, one function), every call held to the actor's org. `StorageDriver.multipart` is
+optional (`MultipartCapability`, `multipart.ts`); every shipped disk has one: s3 over its signed
+wire (`driver-s3-multipart*.ts`), local and memory over a part store (`multipart-staged.ts`), whose
+part URLs carry `x-upload`/`x-part` inside the HMAC and land through `acceptSignedPart`. In the
+browser, `uploadFile({ file, grant, multipart })` switches at `partThresholdBytes` (64 MiB): four
+parts in flight, each retried with core's `retry`, `resume: grant` sends only what `listParts`
+lacks. `completeUpload` reads the etags on the server, so no bucket CORS exposes `ETag`.
+`signPart` and `completeUpload` REQUIRE the grant's `policy`: a part no object under `maxBytes`
+holds, or an assembled total past it, is `X_STORAGE_TOO_LARGE`. The declared `size` is the
+client's claim and the server keeps no grant, so the policy is the bound.
+
+| Code | When |
+|---|---|
+| `X_STORAGE_MULTIPART_UNSUPPORTED` | the driver has no `multipart` |
+| `X_STORAGE_UPLOAD_UNKNOWN` | the session was never opened, or is completed or aborted |
+| `X_STORAGE_PARTS_INVALID` | a named part is missing, out of order, has another etag, or is under 5 MiB and not the last |
+
 ## Attachments and orphans
 
 An upload happens **before** the row it belongs to exists, so it lands at
@@ -397,9 +452,10 @@ 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, 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 call after the source is gone, with the attached key present, is `X_STORAGE_ALREADY_PROMOTED` (409, `meta.attachedKey`): an earlier call moved the bytes, so this one answers the row that holds them and never deletes that key. 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. Then one ranged read of the first 64 KiB through `validateStoredHead`, because it binds no type or bytes either: a contradiction is `X_STORAGE_TYPE_REJECTED`, and it stays pending too. The URL stays valid after that read, so `copy(from, to, { ifMatch })` names the revision judged (`X_STORAGE_OBJECT_CHANGED`, on s3 a signed CopyObject), and the copy is checked: another size is refused and deleted, and an etag that differs or is unknown (SSE-KMS mints one per copy) means the copy's own head is judged. A call after the source is gone, with the attached key present, is `X_STORAGE_ALREADY_PROMOTED` (409, `meta.attachedKey`): an earlier call moved the bytes, so this one answers the row that holds them and never deletes that key. 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 |
+| `deleteVariants({ disk, key })` | `{ deleted, failed }` for every stored variant of one source, every revision (`list({ prefix: `${key}@` })`). **An erasure of one object must call it**: `disk.delete` leaves the variants' bytes behind. The source is the caller's to delete; a variant keeps its prefix, so an org-wide erasure by prefix already collects them |
 
 The filename contributes nothing but its extension, and only if it matches `.[a-z0-9]{1,12}`.
 `sweepOrphans` can only reach the `pending/` prefix of one org — a sweep that could touch an
@@ -424,12 +480,20 @@ const grant = await grantUpload({ disk, orgId, request, quarantine: true });
 
 // promoteAttachment on that key throws X_STORAGE_QUARANTINED. Your scan job decides:
 const released = await releaseQuarantine({ disk, key, orgId });   // clean
-await promoteAttachment({ disk, key: released, orgId, target });
+await promoteAttachment({ disk, key: released, orgId, target, policy });
 ```
 
 Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan, so
 `sweepOrphans` collects it with no second prefix to walk.
 
+## A person's objects, for a subject export or erase
+
+`storageSubjectTarget(() => disk(), keysOf, { name? })` is a `defineSubject({ targets })` entry
+(`@ultimat3/jobs`): `keysOf(subject)` answers the person's keys (a list, or `disk().list({ prefix })`
+over a prefix the app owns). The export lists each object that exists (`STORAGE_SUBJECT_COLUMNS`);
+the erase deletes them in bounded batches. There is no listing by owner: a key the app does not
+name is not found.
+
 ## Errors
 
 | Code | Fires when |
@@ -443,6 +507,7 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_URL_INVALID` | a signed request that does not match what was signed — edited constraint, wrong base, wrong method, contradicting `Content-Type` |
 | `X_STORAGE_URL_EXPIRED` | the grant's window closed; the signature was fine |
 | `X_STORAGE_ORG_MISMATCH` | the key is well-formed and unforged, and belongs to another org |
+| `X_STORAGE_UPLOAD_SIZE_UNDECLARED` | `grantUpload` with no whole `request.size` of at least 1, or `signedUrl({ maxBytes })` on s3 with no `contentLength` |
 | `X_STORAGE_UPLOAD_FAILED` | client half: the presigned `PUT` answered non-2xx or never landed |
 | `X_STORAGE_DELETE_FAILED` | the disk REFUSED a delete — denied `s3:DeleteObject`, a throttle, an expired credential, a read-only mount. An **absent** key is still not an error |
 | `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 |
@@ -473,6 +538,12 @@ 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.
 
+`warmVariants({ disk, key, widths, formats })` (`image-warm.ts`) writes every width x format of a
+stored image under the key `/media` reads — `variantKey(key, { width, format, revision })`, the
+revision off the etag of the bytes it read — so the job an upload enqueues pays the decode and no
+visitor does. Answers `{ written, failed, skipped }`: a width above the source's is skipped, a coded
+failure (an `avif`) is one entry and the rest are still written. `As of 2026-11`.
+
 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
@@ -480,6 +551,14 @@ whole numbers of at least 1 on `variantKey` and `fitDimensions` (`X_INVARIANT` o
 `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.
 
+`variantKey(key, { revision })` adds `r<8 hex>` (`hero.png@w640-r0123abcd.webp`), so a variant names
+the bytes it was made from; absent, the key is byte-identical to one minted without it.
+`variantRevision(etag)` is that part of an etag, however a provider quoted it, or `undefined` when it
+cannot tell two revisions apart. `variantFormatOf(contentType)` maps a stored `png`, `jpeg` or `webp`
+to its format and anything else to `undefined`. A key the route cannot state from those two is a
+variant served and never stored. `variantSourceOf(key)` reads a revisioned key back into
+`{ source, revision }`, which is how a route refuses a variant whose source is gone or overwritten.
+
 **`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`,
@@ -500,3 +579,14 @@ the outputs that keep alpha. The encoded size is always exactly `fitDimensions()
 the box, it does not letterbox to it. `blurPlaceholder()` returns a ThumbHash PNG `data:` URI, at
 most 32px on its long edge.
 `bun test` from `packages/storage`.
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `CopyOptions` | `copy(from, to, { ifMatch })`: the source's `etag` as this disk reported it |
+| `DeleteVariantsInput` | what `deleteVariants` takes: `{ disk, key }` |
+| `StoredHeadCandidate` | what `validateStoredHead` reads: the key, the type, the first bytes and the WHOLE object's size |
+| `ValidatedHead` | what `validateStoredHead` answers |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/storage",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "storage",
+    "uploads",
+    "s3",
+    "files"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Storage-And-Uploads",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -32,6 +42,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0"
+    "@ultimat3/core": "30.1.0"
   }
 }

package/src/accept-part.ts

@@ -0,0 +1,30 @@
+// Single responsibility: the one decision a part PUT on `/_storage` is made of, on a disk that signs
+// its own part URLs — verified, held to the actor's tenant, bounded by the signed length, then
+// handed to the disk's open session. Transport-free, as `accept.ts` is: the route owns the request.
+
+import { type SignedRequestInput, signedUploadConstraints } from './accept';
+import { signedUrlRejected, tooLarge } from './errors';
+import { multipartUnsupported } from './errors-multipart';
+import type { UploadedPart } from './multipart';
+
+export interface AcceptSignedPartInput extends SignedRequestInput {
+  readonly bytes: Uint8Array;
+}
+
+/**
+ * Store one part, or refuse. The URL must be a part URL — a single PUT's URL is
+ * `acceptSignedUpload`'s — and the disk must keep parts itself (`multipart.receivePart`); an s3
+ * part never reaches this process. An upload that is not open is `X_STORAGE_UPLOAD_UNKNOWN`.
+ */
+export async function acceptSignedPart(input: AcceptSignedPartInput): Promise<UploadedPart> {
+  const constraints = await signedUploadConstraints(input);
+  const { key, part, maxBytes } = constraints;
+  if (part === undefined) {
+    throw signedUrlRejected('not-a-part', `"${key}" was signed for the object, not one part`);
+  }
+  const size = input.bytes.byteLength;
+  if (maxBytes !== undefined && size > maxBytes) throw tooLarge(key, size, maxBytes);
+  const receive = input.disk.multipart?.receivePart;
+  if (receive === undefined) throw multipartUnsupported(input.disk.name, key);
+  return receive.call(input.disk.multipart, key, part.uploadId, part.partNumber, input.bytes);
+}

package/src/accept.ts

@@ -142,6 +142,13 @@ export async function signedUploadConstraints(
 export async function acceptSignedUpload(input: AcceptSignedUploadInput): Promise<StorageObject> {
   const constraints = await constraintsFor(input, 'PUT');
   const key = constraints.key;
+  // A part URL writes one part of an open upload, never the object: `acceptSignedPart` takes it.
+  if (constraints.part !== undefined) {
+    throw signedUrlRejected(
+      'part',
+      `"${key}" was signed for one part of an upload, not the object`,
+    );
+  }
 
   // A PUT signed with no content type bounds nothing — any bytes, any type, at that key. The
   // grant always sets one, so this is a hand-rolled URL, and refusing is the only fail-closed

package/src/attachment.ts

@@ -8,9 +8,10 @@ import type { Clock } from '@ultimat3/core';
 import { assert, finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
 import type { StorageDriver, StorageListEntry, StorageObject } from './driver';
 import { objectNotFound, orgMismatch, tooLarge } from './errors';
-import { alreadyPromoted, notPending, quarantined } from './errors-promote';
-import { isWithinOrg, orgPrefix, scopedKey } from './path';
+import { alreadyPromoted, notPending, objectChanged, quarantined } from './errors-promote';
+import { assertSafeKey, isWithinOrg, orgPrefix, scopedKey } from './path';
 import type { UploadPolicy } from './upload';
+import { SNIFF_WINDOW_BYTES, validateStoredHead } from './upload';
 
 /** The one segment an unattached upload lives under. `sweepOrphans` reads only this prefix. */
 export const PENDING_SEGMENT = 'pending';
@@ -126,13 +127,61 @@ export interface PromoteAttachmentInput {
   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.
+   * The policy the upload was GRANTED under — required, never defaulted. A URL an app signed itself
+   * may carry no size, so `policy.maxBytes` binds nothing until this call measures the object; a
+   * default here would silently replace an app's own ceiling with the framework's.
    */
   readonly policy: UploadPolicy;
 }
 
+/** The head window of one stored object, under the type it is stored as. */
+async function judge(
+  disk: StorageDriver,
+  object: StorageObject,
+  key: string,
+  policy: UploadPolicy,
+): Promise<void> {
+  const head =
+    object.size === 0
+      ? new Uint8Array()
+      : (await disk.get(key, { range: [0, SNIFF_WINDOW_BYTES - 1] })).bytes;
+  validateStoredHead(
+    { key, declaredContentType: object.contentType, head, size: object.size },
+    policy,
+  );
+}
+
+/**
+ * `ifMatch` is the first line and this the second, for a disk whose `copy` honours no condition.
+ * The upload URL stays valid after the sniff, so a copy is only trusted once it is known to be the
+ * revision judged. Another size is another object, whatever else agrees.
+ *
+ * An etag alone does not settle it either way. An empty one says nothing, and an SSE-KMS or SSE-C
+ * bucket mints a new etag per copy, so refusing on a difference would refuse every promotion there.
+ * So a copy that cannot be proved the same is judged itself, by the rule the source just passed:
+ * what lands on the row's key has been looked at either way. A refusal leaves nothing attached; a
+ * delete that fails raises its own code, because the bytes are still there.
+ */
+async function assertCopyIsWhatWasJudged(
+  disk: StorageDriver,
+  judged: StorageObject,
+  copy: StorageObject,
+  policy: UploadPolicy,
+): Promise<void> {
+  const proved =
+    judged.etag !== '' && copy.etag === judged.etag && copy.contentType === judged.contentType;
+  if (proved && copy.size === judged.size) return;
+  try {
+    if (copy.size !== judged.size) {
+      throw objectChanged(copy.key, `${judged.size}B`, `${copy.size}B`);
+    }
+    await judge(disk, copy, copy.key, policy);
+  } catch (error) {
+    await disk.delete(copy.key);
+    throw error;
+  }
+}
+
 /**
  * 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
@@ -142,6 +191,12 @@ export interface PromoteAttachmentInput {
  * 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.
  *
+ * SNIFFED before it moves, off a head window. A provider's presigned PUT binds method, expiry and at
+ * most a size, so a bucket holds whatever bytes and whatever type the uploader sent, and this is the first
+ * code that looks: bytes that contradict the stored type are `X_STORAGE_TYPE_REJECTED`, and stay
+ * pending too. A ranged read because `maxGetBytes` bounds the range, never the object. An overwrite
+ * after that read is `X_STORAGE_OBJECT_CHANGED`, or the copy itself is judged, and never lands.
+ *
  * A source that is gone with the destination already there is `X_STORAGE_ALREADY_PROMOTED`
  * (409, `meta.attachedKey`), never the destination answered as if this call had moved it. 27.1.0
  * answered it: a confirm sent twice then inserted a second row for one key, that insert failed,
@@ -179,7 +234,13 @@ export async function promoteAttachment(input: PromoteAttachmentInput): Promise<
   if (pending.size > input.policy.maxBytes) {
     throw tooLarge(input.key, pending.size, input.policy.maxBytes);
   }
-  const object = await disk.copy(input.key, attached);
+  await judge(disk, pending, input.key, input.policy);
+  const object = await disk.copy(
+    input.key,
+    attached,
+    pending.etag === '' ? undefined : { ifMatch: pending.etag },
+  );
+  await assertCopyIsWhatWasJudged(disk, pending, object, input.policy);
   await disk.delete(input.key);
   return object;
 }
@@ -251,3 +312,35 @@ export async function sweepOrphans(input: SweepOrphansInput): Promise<SweepResul
   } while (cursor !== null);
   return { deleted, failed };
 }
+
+export interface DeleteVariantsInput {
+  readonly disk: StorageDriver;
+  /** The SOURCE key. Its variants are every key that opens with it and `@`. */
+  readonly key: string;
+}
+
+/**
+ * Delete every stored variant of one source, of every revision, and answer as `sweepOrphans` does:
+ * a refusal is recorded and the walk continues, so an erasure never reports what is still there.
+ * The source itself is the caller's to delete. `@` is in the prefix, so `x.png2@w1.webp` is
+ * another source's variant and stays.
+ */
+export async function deleteVariants(input: DeleteVariantsInput): Promise<SweepResult> {
+  const prefix = `${assertSafeKey(input.key)}@`;
+  const deleted: string[] = [];
+  const failed: SweepFailure[] = [];
+  let cursor: string | null = null;
+  do {
+    const page = await input.disk.list({ prefix, cursor });
+    for (const object of page.rows) {
+      try {
+        await input.disk.delete(object.key);
+        deleted.push(object.key);
+      } catch (error) {
+        failed.push({ key: object.key, reason: renderThrowable(error) });
+      }
+    }
+    cursor = page.nextCursor;
+  } while (cursor !== null);
+  return { deleted, failed };
+}

package/src/byte-pump.ts

@@ -0,0 +1,46 @@
+// Single responsibility: the one counting read of a body whose length is the sender's: `put()`
+// buffering a stream and `putStream` writing one both come through here. The caller says where the
+// chunks go and which refusal the limit raises; none of them decides when the body is too long.
+
+import { assert, describeValue } from '@ultimat3/core';
+
+export interface PumpLimit {
+  readonly driver: string;
+  readonly maxBytes: number;
+  /** The error to throw past `maxBytes`, given how far the body had got. */
+  readonly refuse: (total: number) => Error;
+}
+
+/**
+ * Every chunk handed to `sink` in order, and how many bytes they came to. Past the limit the sink
+ * sees nothing more. The reader is cancelled on every way out, so a refused body stops arriving
+ * rather than filling a socket buffer nobody will read. An already-closed stream answers that with
+ * a no-op.
+ */
+export async function pumpBounded(
+  body: ReadableStream<Uint8Array>,
+  limit: PumpLimit,
+  sink: (chunk: Uint8Array) => void | Promise<void>,
+): Promise<number> {
+  const reader = body.getReader();
+  let total = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) return total;
+      assert(
+        next.value instanceof Uint8Array,
+        `the stream handed to the ${limit.driver} disk yielded a chunk that is not a Uint8Array (${describeValue(next.value)})`,
+        'stream.pipeThrough(new TextEncoderStream())   # bytes, never strings',
+      );
+      total += next.value.byteLength;
+      if (total > limit.maxBytes) throw limit.refuse(total);
+      // Awaited only when the sink is async: a needless await is one more turn in which the stream
+      // pulls ahead, and a refused body must have pulled as little as possible.
+      const pending = sink(next.value);
+      if (pending !== undefined) await pending;
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}