@ultimat3/storage 30.9.0 → 31.1.0

package/CLAUDE.md

@@ -1,6 +1,7 @@
 # @ultimat3/storage — agent notes
 
 Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
+A rule marked `†` has its full text in [`docs/history/storage-rules.md`](../../docs/history/storage-rules.md).
 
 - May import: `@ultimat3/core`, `@ultimat3/schema`. Nothing else. No npm dependencies.
 - Must NOT know about HTTP, entities, actions, render — a route calls `acceptSignedUpload()`,
@@ -34,7 +35,7 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 | Keys | every driver method starts with `assertSafeKey()`. No exceptions, no sanitising. `META_DIR` (`.meta`) is a reserved first segment on every driver — see below |
 | Time | take a `Clock`; never `Date.now()` |
 | Bytes | `Uint8Array \| ReadableStream \| Blob`. Never a base64 string, never unbounded — `toBytes(body, limit)` |
-| Exports | explicit in `src/index.ts`; no `export *` |
+| Exports | explicit in `src/index.ts`; no `export *`. `./adapter` (`adapter.ts`): `StorageDriver`, its shapes, the errors and helpers a driver raises with — the `storage` port; no installer (the boot reads `runtime.ts`'s `storage` driver as its default disk); the `uploadScanner` port + installer |
 
 | File | Owns |
 |---|---|
@@ -67,11 +68,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-variant.ts` | `variant()`: one kept variant, made by an `images` driver PASSED IN (seo's, structurally) |
+| `upload-scanner*.ts` / `upload-scan.ts` | the `uploadScanner` port + memory (EICAR) reference; `promoteAttachment` scans a per-attempt copy |
 | `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()` |
+| `storage-instrument.ts` | each resolved disk: `storage.<verb>` bus event + client span |
 | `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, `sweepOrphans` and `deleteVariants` |
+| `attachment.ts` | `pending/` → row promotion, `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 |
@@ -82,21 +86,10 @@ 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. `copy()` holds BOTH
-  keys' turns (`inTurnOfBoth`, key order): measured in one and read in the other, an overwritten
-  source committed new bytes under the old etag.
+- **The local disk refuses a key that is another key's path** (`X_STORAGE_KEY_CONFLICT`, `claim()`);
+  pinned, not fixed — changing the layout needs a migration. †
+- **The local commit order is marker → sidecar → bytes → clear marker. Do not reorder**; one key's
+  writers and `get()` queue in-process (`keyedQueue`), `copy()` holds both keys' turns. †
 - **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.
@@ -110,21 +103,14 @@ Gotchas:
   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
-  agree it pins the DIVERGENCE, with the reason — that is the honest form, and it still fails the
-  day either half changes.
-- **The local `list()` globs with `dot: true`, and the `META_DIR` skip is the real filter.**
-  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 driver's semantics are `storageDriverConformance`'s** (`@ultimat3/testing/conformance`);
+  what only two disks share is pinned in `driver-parity.test.ts`, divergences with their reason. †
+- **The local `list()` globs with `dot: true`, and the `META_DIR` skip is the real filter.** †
 - **A `list({ limit })` is a positive integer or a refusal** — `resolveListLimit` at the
-  `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
-  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.
+  `ListOptions` seam, so every disk answers one way. Core's `assert` (`X_INVARIANT`);
+  `storageDriverConformance` holds each driver to it.
+- **`list()` answers core's `Page<StorageListEntry>`** (`pageOf`); a cursor only when a row past the
+  page exists. †
 - **`META_DIR` is reserved case-INSENSITIVELY** (`As of 2026-08`), exactly as `isTenantScoped`
   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.
@@ -142,84 +128,53 @@ 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`.
-- **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.
+- **A grant binds its size on every disk**: s3 signs `content-length` (`presignAwsUrl`), local/memory
+  hold `x-max`; `maxBytes` with no `contentLength` on s3 is `X_STORAGE_UPLOAD_SIZE_UNDECLARED`. †
+- **`putStream` on s3 is signed multipart, never `S3File.writer()`** (Bun 1.4.4: `end(error)` COMPLETES). 8 MiB parts, ≤ `STREAM_PART_BUFFERS` held; parts settle before the abort; a Complete can fail with 200 + `<Error>`.
+- **s3 `copy()` is a signed CopyObject**, past 5 GiB `UploadPartCopy`: Bun's `write(S3File)` dropped `cacheControl`/metadata.
+- **`stream(key, { etag })` never serves another revision**: local re-checks the etag at the first pull, never the inode (ext4 reuses it; `highWaterMark: 0`: an unread body holds no fd); s3 sends `If-Match`.
+- **The upload route streams** (`accept-stream.ts`). Keys refuse `:`, a trailing `.`, Win32 device names; `contentType`/`cacheControl` are `HEADER_VALUE` on every disk.
 - **`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
-  is a GDPR erasure report certifying data that is still in the bucket. The s3 driver classifies
-  structurally (`code` in `NoSuchKey`/`NotFound`/`ENOENT`, or a 404 `statusCode`/`status`; an
-  `S3Error` is a plain `Error` with those fields and every read of one can throw), the local
-  driver on `ENOENT`. Everything else is `X_STORAGE_DELETE_FAILED`, whose `fix` the DRIVER
-  supplies — the command that reproduces the refusal differs per disk.
-- **`toBytes` takes a `ByteLimit`, and there is no unbounded variant.** `put()` buffers, so the
-  ceiling is what keeps a route piping a 4GB body into `disk.put()` from being an OOM kill rather
-  than a refusal. `Uint8Array`/`Blob` are refused on their declared length; a `ReadableStream` is
-  read chunk-by-chunk and **cancelled** past the line, so at most one chunk over is ever held.
-  Default `maxPutBytes` is `DEFAULT_MAX_UPLOAD_BYTES` — one constant, imported by both drivers
-  from `upload.ts`, because the server-side ceiling and the upload ceiling are the same fact.
-- **`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. 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.
-  `promoteAttachment` refuses a quarantined key (`X_STORAGE_QUARANTINED`); `releaseQuarantine` is
-  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.
+- **`delete()` is idempotent for an ABSENT key and for nothing else** — a swallowed refusal made
+  `sweepOrphans` certify an erasure that never happened. s3 classifies structurally (`NoSuchKey`/
+  `NotFound`/`ENOENT` or a 404), local on `ENOENT`; else `X_STORAGE_DELETE_FAILED`, fix per driver.
+- **`toBytes` takes a `ByteLimit`, and there is no unbounded variant**; one default,
+  `DEFAULT_MAX_UPLOAD_BYTES` (`upload.ts`). †
+- **`serverSideEncryption` is declared and refused by BOTH drivers.** Full rule: `docs/history/storage.md`.
+- **The `uploadScanner` port is the ONE scan path** (`As of 31.0.0`; the `quarantine: true` segment
+  and `releaseQuarantine` are retired). An out-of-band decision — a review, an async vendor scan —
+  is the verdict `hold`, keyed by `ScanInput.pendingKey`: `X_STORAGE_QUARANTINED` (409), upload
+  kept pending, attempt deleted, no policy overrides it. A scanner that holds declares `holds: true`
+  (else its `hold` is `X_INVARIANT`), and its outage then refuses even under `'accept'`. A targeted
+  grant is refused while a scanner is installed (`X_STORAGE_TARGET_UNSCANNED`): it skips promotion.
+  Ultimate ships no scanner vendor (axiom 8).
+  **No verdict fails closed in every environment** (`onScanUnavailable` absent = `'refuse'`).
 - **`StorageListEntry` vs `StorageObject`.** A listing's `contentType` is optional; a `get()`'s is
   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
-  `text/html` and have a route serve attacker HTML from the app's origin. Reserved in
-  `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.
+- **`META_DIR` lives in `path.ts`, reserved in `assertSafeKey` on every driver** — the sidecar
+  namespace must never be a writable key. †
 - **`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.
   `driver-local-boot.test.ts` pins it by mutation.
-- **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`,
-  `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
-  signature); mounting the write half needs that seam question answered first.
+- **The mounted read half is `@ultimat3/cli`'s `runtime-storage.ts`**, gated by policy; no
+  "serve this object" helper here (a second authz path). †
+- `acceptSignedUpload` still has no mounted route: no `StorageDriver` method exposes the signing
+  secret. †
 - `X_NOT_IMPLEMENTED` is core's — it belongs in `STORAGE_BORROWED_ERROR_CODES` (codes, no title)
   and never in the registration call. A `hasErrorCode()` guard there would suppress the
   `X_ERROR_CODE_DUPLICATE` two owners of one code are supposed to get. Tests need `resetStorage()`
   in `beforeEach`.
-- `image.ts` owns no pixels: core's `transformImageBytes`/`blurDataUrl` are the only scaler.
-  Its image failures (`X_IMAGE_UNSUPPORTED`, `X_IMAGE_DECODE_FAILED`) surface unwrapped —
-  wrapping them in a `StorageError` would give one failure two codes. `variantKey` now RAISES
-  core's `imageUnsupported()` as well as passing them through, for that same reason.
-- **`VARIANT_FORMATS` is this package's format vocabulary, and `IMAGE_FORMATS` is core's** (what
-  core can PROBE). `as const satisfies readonly ImageFormat[]` makes it a strict subset by the
-  compiler; `isVariantFormat` takes `string` so `probeImage(bytes).format` narrows with no cast.
-  `scripts/render-modes.ts` holds the `IMAGE_FORMATS` row and `image.test.ts` fails if either core
-  name reappears in `src/index.ts`.
-- `transformImage()` must encode at exactly `fitDimensions()`'s size, and passes `format`
-  explicitly (`?? 'webp'`, which then rejects): bytes that disagree with the `variantKey`
-  extension, or with the `width`/`height` `@ultimat3/seo` inlined, are the layout shift the
-  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.
+- `image.ts` owns no pixels: core's `transformImageBytes` is the only scaler; image failures surface
+  unwrapped. †
+- **`VARIANT_FORMATS` is this package's format vocabulary, and `IMAGE_FORMATS` is core's.** †
+- `transformImage()` encodes at exactly `fitDimensions()`'s size, `format` explicit — anything else
+  is a layout shift. †
 - 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.
+- **No `region` signs for `auto`** (R2's; AWS refuses it) — `regionMismatch()` makes it `X_CONFIG_INVALID` naming `S3_REGION`. Full rule: `docs/history/storage.md`.
 - The signature check runs BEFORE the expiry check. Do not reorder.
 - `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.
@@ -230,31 +185,19 @@ Gotchas:
   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.** 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:
-  `Org/o2/x` and `org/o2/x` are one file on APFS/NTFS, so the fold has to count as tenant-scoped
-  and then fail the exact-case membership test. Do not "simplify" either half.
-- **`AcceptSignedUploadInput.checksum` is what makes `uploadPolicy({ requireChecksum: true })`
-  reachable.** Without it that option could only ever fail, because nothing on the accept path
-  could declare a hash. It travels like `declaredContentType`: the route reads a header and hands
-  it over, and `validateUpload` hashes the bytes itself. The browser half does NOT send one — a
-  custom header on an S3 presigned PUT is a signature question this package cannot answer.
+- **`accept.ts` asks the `isTenantScoped`/`isWithinOrg` PAIR, as `runtime-storage.ts` does.** Do not
+  "simplify" either half. †
+- **`AcceptSignedUploadInput.checksum` is what makes `requireChecksum: true` reachable**; the browser
+  half sends none. †
 - `orgId` is required on both halves of `accept.ts` and is the ACTOR's, never a request field. A
   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.
 - **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
-  ships, and the one file slice 15's `browser-transport` guard exempts for it — the header says so.
-- **`fetchSignedPut` goes through `@ultimat3/core`'s `clientTransport`** (`As of 2026-09-22`,
-  plan 101 slice 05): `rawBody` sends the `Blob` verbatim under the grant's content type with no
-  default header, and `decodeError` keeps a refusal `X_STORAGE_UPLOAD_FAILED` with the disk's
-  status. A request with no response at all is the transport's `X_CLIENT_TRANSPORT_FAILED` — it was a
-  bare `TypeError` before. This file calls no `fetch`; the XHR above is the one exemption.
+- `upload-client.ts` uses `XMLHttpRequest` for upload progress — the framework's one declared XHR
+  seam. †
+- **`fetchSignedPut` goes through `@ultimat3/core`'s `clientTransport`**; it calls no `fetch`. †
 - **Bundle** (`uploadFile` only, browser, minified, `As of 2026-09-22`): **17,767 B**.
 - `exactOptionalPropertyTypes` is on — declare optional fields as `x?: T | undefined`.
 

package/README.md

@@ -58,15 +58,20 @@ const stored = [...sessions.objects().values()].map((bytes) => new TextDecoder()
 
 Server-side only, like both other drivers: nothing an island imports reaches it.
 
+Every call on a disk `defineStorage` resolves is a `storage.<verb>` event on `@ultimat3/core`'s instrumentation bus (`put`, `get`, `stat`, `copy`, `delete`, `list`; `{ disk, key, bytes?, durationMs, error? }`) inside a `storage.<verb>` client span. `disk()` hands out that instrumented view, so it is not `===` the driver you declared — compare `.name`. A driver you hold directly reports nothing.
+
 `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
-through the pod to rename a 500MB attachment. `localDriver` does a real file copy; `s3Driver`
-hands the source `S3File` to `write()` — Bun exposes no `CopyObject`, so the bytes still cross the
-network, but never this process's heap. Both arguments go through `assertSafeKey`.
+through the pod to rename a 500MB attachment. `localDriver` does a real file copy; `s3Driver` sends
+one signed `CopyObject` (directive COPY), so the bytes never leave the provider and the source's
+type, `cacheControl` and `metadata` travel, as on local and memory. Past CopyObject's 5 GiB ceiling
+it is a multipart `UploadPartCopy` (512 MiB parts, grown past 10,000), every part pinned to the
+revision a HEAD read, carrying the same headers, aborted on any failure. 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
@@ -176,6 +181,16 @@ do {
 
 Before 25.0.0 it was `ListPage { objects, truncated, cursor? }`, its own shape beside core's.
 
+### Writing a driver: `@ultimat3/storage/adapter`
+
+`StorageDriver`, the shapes it reads and answers, the error factories a driver raises
+(`objectNotFound`, `putFailed`, `readFailed`, …) and the helpers every driver refuses with the same
+way (`assertPutOptions`, `toBytes`, `resolveListLimit`, `etagOf`). Hand one to the boot as
+`storage: myDriver()` in `apps/web/runtime.ts`: it becomes the default disk, registered under the
+driver's `name`, in place of the `S3_ENDPOINT`/embedded-disk decision (31.0 — the field took a whole
+`Storage` before). Several disks stay the app's `defineStorage()`. The suite is
+`@ultimat3/testing/conformance`'s `storageDriverConformance`.
+
 ## `put()` is for objects that fit in memory
 
 `put()` buffers the whole body — size and checksum have to be known before the object exists —
@@ -200,12 +215,17 @@ in a bucket unmeasured, so a later `get()` of it was heap growth the uploader pi
 
 `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`,
+past the end is `X_STORAGE_RANGE_UNSATISFIABLE`. `stream(key, { etag })` and
+`streamRange(key, range, { etag })` serve that revision only — another is `X_STORAGE_OBJECT_CHANGED`
+(409): s3 sends `If-Match`, local checks the etag at the call and again at the first read, memory compares. `/_storage`
+pins every read to the etag its headers came from. `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
+8 MiB parts (doubled every 1,000 parts, so 10,000 reach past S3's 5 TiB; never derived from
+`maxBytes`), up to `STREAM_PART_BUFFERS` (4) parts held at once — in flight plus the one filling,
+so memory is at most 32 MiB per stream — 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`.
@@ -418,8 +438,13 @@ Neither owns a `Request`, a `Response` or a status number — mounting is the ho
 **Step 3 ships.** `As of 2026-09-24` `@ultimat3/cli` mounts `PUT /_storage/:disk/*key` beside the
 `GET` in `x dev` and `runRole` (#523), so an app writes steps 1 and 2 only. The route calls
 `signedUploadConstraints({ url, disk, orgId })` first. That is the verified PUT constraints with
-no bytes, and the signed `maxBytes` caps the body read. Then it calls `acceptSignedUpload` with a
-policy built from the grant's own signed type and ceiling. The routes serve `definedStorage()`,
+no bytes, and the signed `maxBytes` caps the body read. Then it calls `acceptSignedUploadStream`
+with a policy built from the grant's own signed type and ceiling: the first 64 KiB are sniffed, the
+rest piped into `disk.putStream`, so memory per upload is the window, not the body. A body that
+ends inside the window, an XML type, and a required checksum nobody declared are read whole and
+judged by `acceptSignedUpload`. A local or memory disk given `maxRequestBytes` (the app's
+`http.maxRequestBodyBytes`) refuses at signing a single-request grant past it (`X_STORAGE_TOO_LARGE`,
+the fix naming `grantMultipart`). 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`
@@ -450,10 +475,8 @@ An upload happens **before** the row it belongs to exists, so it lands at
 | Call | Key |
 |---|---|
 | `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. 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 |
 
@@ -466,31 +489,80 @@ refused delete goes in `failed` with the disk's own words and the sweep keeps go
 array of "deleted" keys put every refusal in it, so an erasure sweep over a bucket whose policy
 had lost `s3:DeleteObject` reported 200 objects gone that were all still there.
 
-### Quarantine is the mechanism; the scanner is your app's
+### Scanning on confirm: the `uploadScanner` port
 
-Magic-byte sniffing closes stored XSS. It is **not** malware scanning, and `application/zip` is
-accepted on purpose as the OOXML container, so a macro-laden `.docx` passes `validateUpload`
-exactly as a clean one does. A scanner is a business decision with a vendor, a licence and a
-latency budget (axiom 8), so what ships is the place to put one — one more segment in a
-convention that already existed:
+`As of 2026-11-09`. An `uploadScanner` in `apps/<app>/runtime.ts` is asked by `promoteAttachment`
+about every upload it attaches. It scans a per-attempt copy (`pending/scan/<random>-<name>`): server
+named, so no presigned URL rewrites it after the scan, and never the row's key, so a refused second
+confirm of a double-click cannot delete the file the first one attached. The clean attempt is what
+is copied onto the row's key:
+
+| Verdict | `promoteAttachment` |
+|---|---|
+| `{ verdict: 'clean' }` | promotes, as without a scanner |
+| `{ verdict: 'infected', signature }` | deletes the pending upload and the attempt, throws `X_STORAGE_UPLOAD_INFECTED` (422, `meta.signature`) |
+| `{ verdict: 'hold', reason }` | deletes the attempt, keeps the upload pending, throws `X_STORAGE_QUARANTINED` (409, `meta.reason`) — a decision made elsewhere has not cleared it yet. No policy overrides it; the same confirm promotes once the scanner answers clean |
+| rejects (daemon down, timeout), or the attempt cannot be read | deletes the attempt, keeps the upload pending, throws `X_STORAGE_SCAN_UNAVAILABLE` (503) — **fail closed by default, in every environment**; `uploadPolicy({ onScanUnavailable: 'accept' })` promotes unscanned instead, unless the scanner declares `holds: true`. An infected or held verdict is refused under either |
 
 ```ts
-const grant = await grantUpload({ disk, orgId, request, quarantine: true });
-// → org/<orgId>/pending/quarantine/<uploadId><ext>
+// apps/web/runtime.ts
+import type { RuntimeOverrides } from '@ultimat3/cli/serve';
+import { memoryUploadScanner } from '@ultimat3/storage';
+// In production, your own UploadScanner here: e.g. one streaming `body` to clamd's INSTREAM
+// over Bun.connect, mapping `OK` → clean, `<sig> FOUND` → infected, anything else → reject.
+export const runtime = {
+  uploadScanner: memoryUploadScanner(),
+} satisfies RuntimeOverrides;
+```
+
+`UploadScanner` (`@ultimat3/storage/adapter`) is `{ name, holds?, scan({ key, pendingKey, size, contentType, body }) }`,
+`body` a `ReadableStream`. `memoryUploadScanner()` is the reference: it flags the EICAR test string
+(`EICAR_TEST_STRING`) anywhere in the stream, across chunk boundaries. Hold your adapter to the
+contract with `behavesLike(uploadScannerConformance, () => yours)` from
+`@ultimat3/testing/conformance`. No scanner ships: ClamAV, a vendor API, its licence and its
+latency budget are the app's (axiom 8). No scanner installed, nothing is scanned.
+
+### Hold: a decision made elsewhere — a review queue, an async vendor scan
+
+Magic-byte sniffing closes stored XSS. It is **not** malware scanning: `application/zip` is the
+OOXML container, so a macro-laden `.docx` passes `validateUpload` as a clean one does. A verdict
+that is not ready inside the confirm is the scanner's `hold`, keyed by `pendingKey` — the upload's
+own key, stable across retries (`key` is the per-attempt copy). One scan path; the v30
+`grantUpload({ quarantine: true })` + `releaseQuarantine` flow is retired.
 
-// 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, policy });
+```ts
+import type { UploadScanner } from '@ultimat3/storage/adapter';
+
+// `approved` is your app's own store — a table a moderator's action writes.
+export const reviewScanner = (approved: (key: string) => Promise<boolean>): UploadScanner => ({
+  name: 'review',
+  holds: true,
+  async scan({ pendingKey, body }) {
+    await body.cancel();
+    return (await approved(pendingKey))
+      ? { verdict: 'clean' }
+      : { verdict: 'hold', reason: 'awaiting a moderator' };
+  },
+});
 ```
 
-Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan, so
-`sweepOrphans` collects it with no second prefix to walk.
+**`holds: true` is required of a scanner that answers `hold`**, and makes its outage always refuse:
+`approved` throwing (your database is down) is `X_STORAGE_SCAN_UNAVAILABLE` even under
+`onScanUnavailable: 'accept'`, because only that store knows what is held. A `hold` from a scanner
+that did not declare it is `X_INVARIANT`, and nothing is attached.
+
+A held upload is still under `pending/`, so `sweepOrphans` collects one nobody ever cleared: keep
+`olderThanMs` past your review window, or spare it with `keep`.
+
+**A grant with a `target` is refused while a scanner is installed** (`X_STORAGE_TARGET_UNSCANNED`,
+`grantUpload` and `grantMultipart` both): its key never passes through `promoteAttachment`, the one
+place a scan runs. Grant with no `target`, then promote.
 
 ## 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`);
+over a prefix the app owns). The export lists each object that exists (columns: `STORAGE_SUBJECT_COLUMNS` in `src/subject-target.ts`);
 the erase deletes them in bounded batches. There is no listing by owner: a key the app does not
 name is not found.
 
@@ -511,8 +583,11 @@ name is not found.
 | `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 |
-| `X_STORAGE_QUARANTINED` | `promoteAttachment` on a key nothing has released from `pending/quarantine/` |
+| `X_STORAGE_TARGET_UNSCANNED` | `grantUpload`/`grantMultipart` with a `target` while an `uploadScanner` is installed — the key would skip the scan |
+| `X_STORAGE_QUARANTINED` | the installed `uploadScanner` answered `hold`: the upload stays pending until it answers clean; `meta.reason` is the scanner's |
 | `X_STORAGE_NOT_PENDING` | `promoteAttachment` on a key outside the org's `pending/` prefix — most often another row's attached key |
+| `X_STORAGE_UPLOAD_INFECTED` | the installed `uploadScanner` found malware in an upload `promoteAttachment` was attaching; both keys are deleted, `meta.signature` names the detection |
+| `X_STORAGE_SCAN_UNAVAILABLE` | the installed `uploadScanner` rejected instead of answering, under the default `onScanUnavailable: 'refuse'`; the upload stays pending for a retry |
 | `X_STORAGE_ALREADY_PROMOTED` | `promoteAttachment` on a pending key an earlier call already moved (a retried or doubled confirm); `meta.attachedKey` names where the bytes are |
 | `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 |
@@ -538,6 +613,24 @@ 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.
 
+`variant(key, { disk, images, width, format? })` (`image-variant.ts`) is ONE variant, kept: made by
+the `images` driver you pass — `runtime.ts`'s `images` port value, `@ultimat3/seo`'s
+`builtinImageDriver({ read })` or a CDN's, any `ImageTransformDriver` (storage takes it structurally;
+it is tier 1 beside seo and imports none of it) — and written under
+`variantKey(key, { width, format, revision })`. A second call is a `stat`, never a decode
+(`{ key, object, created }`); an overwritten source is a new revision, so a new key. `format`
+omitted keeps a png/jpeg/webp source's encoding. Refused with core's `X_IMAGE_UNSUPPORTED`: a source
+that is not a raster image (a PDF, an SVG), a gif/avif source with no `format`, and a driver that
+answers another encoding than the key names. A source overwritten while the driver read it is
+`X_STORAGE_OBJECT_CHANGED`, and nothing is stored. `As of 2026-11-09`.
+
+```ts
+import { builtinImageDriver } from '@ultimat3/seo';
+import { disk, variant } from '@ultimat3/storage';
+const images = builtinImageDriver({ read: async (src) => (await disk().get(src)).bytes });
+const { key } = await variant('org/o1/post/p1/cover/u1.png', { disk: disk(), images, width: 640, format: 'webp' });
+```
+
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "30.9.0",
+  "version": "31.1.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "keywords": [
     "ultimate",
@@ -24,7 +24,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts"
   },
   "files": [
     "src",
@@ -42,6 +43,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0"
+    "@ultimat3/core": "31.1.0"
   }
 }