@ultimat3/storage 21.0.0 → 22.0.0

package/CLAUDE.md

@@ -15,31 +15,16 @@ 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, `As of 2026-08-26`** — `uploadPolicy({ maxBytes })`, both
-  drivers' `maxPutBytes`, `createUploadGrant({ expiresInMs })`, `buildSignedUrl`'s two and the s3
-  driver's presign TTL. There was briefly a private `assertFiniteSignedUrlBound` here saying the
-  same thing in its own words; a second finite-bound path is one that drifts from the shared
-  contract, which is exactly what `jobs`, `realtime` and `query` each proved with a copy of their
-  own. Both presigners now call the one function, which is what `driver-parity.test.ts` needs to
-  stay true.
-  Measured: `uploadPolicy({ maxBytes: Number.NaN })` accepted a 5,000,016-byte PNG through
-  `validateUpload`, because `size > NaN` is false — the one number deciding how much a caller may
-  store stopped deciding anything. Variant `quality` is core's `assertFiniteImageQuality` and NOT a
-  second screen: `variantKey` never reaches the encoder, so a copy that disagreed would mint
-  `q150` keys for bytes `transformImageBytes` then refuses.
-- **The default is taken on `undefined` and on nothing else, `As of 2026-08-26`** —
-  `options.x === undefined ? D : options.x`, never `options.x ?? D`. `??` coalesces on `null` too,
-  so an explicitly blanked key in a decoded JSON config took the default BEFORE the screen above
-  could refuse it: the mirror of the `NaN` half, where one value slips past the guard and the other
-  past the default, and both end in a bound nobody chose. Every site above, `quality` included.
+  `finiteCount` and nothing else** — `uploadPolicy({ maxBytes })`, both drivers' `maxPutBytes`,
+  `createUploadGrant({ 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
+  `x ?? D`: `??` defaults a blanked `null` before the screen can refuse it.
 
-- **`MAX_KEY_LENGTH` is BYTES, and is measured in bytes, `As of 2026-08-26`.** S3's limit is "a
-  sequence of Unicode characters whose UTF-8 encoding is at most 1,024 bytes long", and `path.ts`
-  measured `key.length` — UTF-16 code units — while its message said "chars". A code-unit count is
-  never MORE than the UTF-8 byte count, so a non-ASCII key over the real limit passed this guard
-  and was refused by the store instead: 400 CJK characters is 400 units and 1,200 bytes. Keeping
-  local and remote disks interchangeable is the whole reason the ceiling exists, so it has to be
-  the store's ceiling. Same defect and same fix as `@ultimat3/cache`'s surrogate-key guard.
+- **`MAX_KEY_LENGTH` is UTF-8 BYTES, measured in bytes** — S3's limit. A UTF-16 `length` passed
+  400 CJK characters (1,200 bytes) that the store then refused. Same fix as `@ultimat3/cache`'s
+  surrogate-key guard.
 
 | Rule | |
 |---|---|
@@ -78,16 +63,9 @@ Gotchas:
   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**
-  (`As of 2026-08`). `Bun.Glob('**/*')` matches no dot-prefixed entry, so every object whose key
-  had one — `.hidden.txt`, `org/o1/pending/.x.png`, the `.metadata/a.json` `path.test.ts` pins as
-  legal — was missing from the listing while `put`/`get`/`exists` handled it normally and
-  `s3Driver.list()` returned it: the key space and the listing disagreed by construction.
-  `sweepOrphans` pages through `list()`, so those objects were reported as erased while still on
-  disk — a false erasure report by OMISSION, the same lie a swallowed listing error tells. The
-  `.meta/` skip one line below was unreachable until this landed and this file called it "a second
-  line of defence"; it is now the only thing keeping the sidecar tree out of the object namespace,
-  and it folds case for `isSafeKey`'s reason. Pinned in `driver-parity.test.ts`.
+- **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 `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
@@ -112,14 +90,9 @@ Gotchas:
   for the http error map to render but a 500. `sweepOrphans` walks `list()`, so the local swallow
   was a false-erasure report a layer up. `ENOENT` (a root nobody has written to) is still an empty
   page; everything else is `X_STORAGE_LIST_FAILED`, whose `fix` the DRIVER supplies.
-- **`head()` NEVER reads an object's bytes, and `list()` is why** (`As of 2026-08`). It hashed a
-  sidecar-less object to invent an etag, under a comment saying "`list()` must not read every file
-  it lists" — which is what `list()` then did, one whole buffered object per listed row,
-  sequentially, and `copy()` inherited it, so a copy documented as never routing bytes through the
-  heap buffered the entire source. A listing that cannot know an etag reports `''`, which is what
-  the s3 listing already answers. `get()` hashes out of bytes it already holds; `copy()` passes
-  `hash: true`, because the sidecar it writes at the destination would otherwise carry `etag: ''`
-  as a durable lie.
+- **`head()` and `list()` NEVER read an object's bytes.** A listing that cannot know an etag
+  reports `''`, as the s3 listing does. `get()` hashes bytes it already holds; `copy()` passes
+  `hash: true` so the destination sidecar never records `etag: ''`.
 - **`put({ metadata })` / `put({ cacheControl })` is the one `PutOptions` pair the disks disagree
   about, and it is pinned rather than resolved.** Bun's `S3File.write` exposes `type`, `acl` and
   `storageClass` and no header hook for `x-amz-meta-*` or `Cache-Control`, so `s3Driver` refuses
@@ -181,19 +154,10 @@ Gotchas:
   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({ env })` and `usesDevStorageSecret({ env })` are ONE question about ONE table**
-  (`As of 2026-08-23`). The predicate learned core's `env` slot first, so `dev-runtime.ts`'s guard
-  — `!isLocal({ env }) && usesDevStorageSecret({ env })` — asked about the BOOT while the
-  constructor it guards still read `process.env` for the secret, for `isLocal()` and for the
-  environment its refusal names. An embedding caller whose env is not the process's (`serveApp({ env })`,
-  a test fixture) got the verdict from one table and the behaviour from another, in the dangerous
-  direction: a production boot with no secret, launched from a development shell that has one,
-  signing every grant with the published literal. All three reads now come off `options.env ??
-  process.env`, so a bare `localDriver({ root })` is unchanged and additive.
-  `driver-local-boot.test.ts` pins it by mutation — reverting any one read to `process.env` fails.
-  That file is the CONSTRUCTION half, split off `driver-local.test.ts` at the line ceiling along
-  the seam the guard already draws: nothing in it writes a byte, so it needs no temporary
-  directory, and `driver-local.test.ts` keeps everything the disk actually does with an object.
+- **`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 `dev-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
@@ -212,19 +176,11 @@ Gotchas:
   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.** Until
-  9.0.0 both packages exported `IMAGE_FORMATS` **and** `ImageFormat` from their own barrels over
-  different sets (core: `png|jpeg|webp|avif|gif|svg`, what it can PROBE; storage: `avif|webp|jpeg|png`),
-  so a caller narrowing on storage's held a type saying `gif` and `svg` could not occur and a
-  `probeImage()` value that was one — and `variantKey('photos/hero.gif', { format })` minted
-  `photos/hero@full.undefined`, a well-formed writable key naming a file nothing can serve. The set
-  is now a strict subset **by the compiler**: `as const satisfies readonly ImageFormat[]`, so a
-  member core cannot name is a build error here. `isVariantFormat` takes `string` on purpose, so
-  `probeImage(bytes).format` narrows through it with no cast. `avif` is in the set and `gif`/`svg`
-  are not because the question is what a variant KEY can carry, never what core can transform —
-  core decodes `gif` perfectly well, and naming this set `TRANSFORMABLE_FORMATS` would have been
-  the same lie one rename later. `scripts/render-modes.ts` holds the `IMAGE_FORMATS` row (`by:
-  'name'`) and `image.test.ts` fails the day either core name reappears in `src/index.ts`.
+- **`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
@@ -281,8 +237,8 @@ Gotchas:
   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.
-- **Bundle, `bun build --target=browser --minify`, `import { uploadFile } from '@ultimat3/storage'`**
-  (`As of 2026-09-22`): **11,822 B** at 20.2.1, **17,767 B** on `clientTransport`. The +5.9 kB is
-  core's transport graph, paid only where the chunk did not already carry it — an island that
-  also calls an action or a query already does.
+- **Bundle** (`bun build --target=browser --minify`, `uploadFile` only, `As of 2026-09-22`):
+  **17,767 B** on `clientTransport`; the +5.9 kB over 20.2.1 is core's transport graph.
 - `exactOptionalPropertyTypes` is on — declare optional fields as `x?: T | undefined`.
+
+Why each rule above is shaped the way it is: [`docs/history/storage.md`](../../docs/history/storage.md).

package/README.md

@@ -106,7 +106,7 @@ The HMAC covers the **constraints**, not just the key —
 A client that edits `?x-max=` invalidates the signature — it cannot widen what it was granted.
 
 The HMAC key is `signingSecret`, else `STORAGE_SIGNING_SECRET`, else the shipped
-`DEV_SIGNING_SECRET` — and **only in `development` or `test`**. Anywhere else `localDriver` refuses
+`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
 literal: the dev literal is published in this repo, so signing with it lets anyone mint a `PUT` for
 any key with a `maxBytes` and `contentType` of their choosing, which `acceptSignedUpload` then
@@ -189,9 +189,9 @@ 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 |
+| `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`) |
 | `releaseQuarantine({ disk, key, orgId })` | quarantine → pending; returns the released key |
-| `sweepOrphans({ disk, orgId, olderThanMs })` | `{ deleted, failed }` for stale `pending/` keys |
+| `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 |
 
 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
@@ -239,11 +239,21 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `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_NOT_PENDING` | `promoteAttachment` on a key outside the org's `pending/` prefix — most often another row's attached key |
 | `X_NOT_IMPLEMENTED` | S3 user metadata / cache-control; `serverSideEncryption` on either driver |
 | `X_ENV_MISSING` | core's: S3 credential env vars, or a `localDriver` built outside development where neither `signingSecret` nor `STORAGE_SIGNING_SECRET` holds a secret other than the published `DEV_SIGNING_SECRET` |
 | `X_IMAGE_UNSUPPORTED` | core's: an `avif` encode, a source no built-in decoder reads, or a `variantKey` format no variant can carry |
 | `X_IMAGE_DECODE_FAILED` | core's: truncated or corrupt image bytes |
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `StorageError` | any `StorageErrorCode` — `STORAGE_ERROR_CODES` | `src/errors.ts` |
+
 ## Images
 
 `variantKey()`, `srcsetDescriptors()`, `fitDimensions()` are pure — `@ultimat3/seo` builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "21.0.0"
+    "@ultimat3/core": "22.0.0"
   }
 }

package/src/attachment.ts

@@ -5,9 +5,9 @@
 // so the tenant prefix is a construction, not a check somebody remembered to write.
 
 import type { Clock } from '@ultimat3/core';
-import { renderThrowable, systemClock } from '@ultimat3/core';
+import { finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
 import type { ListPage, StorageDriver, StorageListEntry, StorageObject } from './driver';
-import { orgMismatch, quarantined } from './errors';
+import { notPending, orgMismatch, quarantined } from './errors';
 import { isWithinOrg, orgPrefix, scopedKey } from './path';
 
 /** The one segment an unattached upload lives under. `sweepOrphans` reads only this prefix. */
@@ -137,6 +137,9 @@ export interface PromoteAttachmentInput {
  */
 export async function promoteAttachment(input: PromoteAttachmentInput): Promise<StorageObject> {
   if (!isWithinOrg(input.key, input.orgId)) throw orgMismatch(input.key, input.orgId);
+  // Pending, not merely in-org: an attached key a client sent back belongs to another row, and the
+  // 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);
   const name = input.key.slice(input.key.lastIndexOf('/') + 1);
   const attached = attachmentKey(input.orgId, input.target, name);
@@ -187,7 +190,10 @@ export interface SweepResult {
  */
 export async function sweepOrphans(input: SweepOrphansInput): Promise<SweepResult> {
   const clock = input.clock ?? systemClock;
-  const cutoff = clock.now().getTime() - input.olderThanMs;
+  // Screened first: `now - NaN` is NaN and `lastModified > NaN` is false — the "old enough"
+  // answer — so `olderThanMs: NaN` deleted an upload created a moment ago.
+  const olderThanMs = finiteCount('sweepOrphans', 'olderThanMs', input.olderThanMs, 0);
+  const cutoff = clock.now().getTime() - olderThanMs;
   const prefix = pendingPrefix(input.orgId);
   const deleted: string[] = [];
   const failed: SweepFailure[] = [];

package/src/driver-local.ts

@@ -190,8 +190,11 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     supplied === undefined || supplied === '' || supplied === DEV_SIGNING_SECRET
       ? undefined
       : supplied;
-  if (configured === undefined && !isLocal({ env }))
-    throw signingSecretMissing(resolveEnvironment({ env }));
+  // FAILS CLOSED: a process that names no environment resolves as `production` here, the answer
+  // core's `assertNoDevSecretsOutsideLocal` gives. `isLocal`'s own fallback is `development`, so the
+  // process that forgot to say signed with the published key — exactly the one that must not.
+  if (configured === undefined && !isLocal({ env, fallback: 'production' }))
+    throw signingSecretMissing(resolveEnvironment({ env, fallback: 'production' }));
   const secret = configured ?? DEV_SIGNING_SECRET;
 
   const filePath = (key: string): string => `${root}/${key}`;

package/src/errors.ts

@@ -20,6 +20,7 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_DELETE_FAILED',
   'X_STORAGE_LIST_FAILED',
   'X_STORAGE_QUARANTINED',
+  'X_STORAGE_NOT_PENDING',
 ] as const;
 
 /**
@@ -55,6 +56,7 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_DELETE_FAILED: 'the object could not be deleted',
   X_STORAGE_LIST_FAILED: 'the objects could not be listed',
   X_STORAGE_QUARANTINED: 'the object is still in quarantine',
+  X_STORAGE_NOT_PENDING: 'the key is not a pending upload',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -295,6 +297,19 @@ export const quarantined = (key: string, orgId: string): StorageError =>
     meta: { key, orgId },
   });
 
+/**
+ * A key inside the org and outside its `pending/` prefix — most often another row's attached key
+ * a client sent back. Promotion copies then deletes, so accepting it moved the victim's file onto
+ * this row and removed it from theirs.
+ */
+export const notPending = (key: string, orgId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_NOT_PENDING',
+    cause: `"${key}" is not under org "${orgId}"'s pending/ prefix, so it is not an upload waiting for a row — it may already belong to one`,
+    fix: 'promote the key grantUpload returned with no target: promoteAttachment({ disk, key: pendingKey(orgId, name), orgId, target })',
+    meta: { key, orgId },
+  });
+
 /** The key is well-formed and unforged, and still belongs to somebody else. */
 export const orgMismatch = (key: string, orgId: string): StorageError =>
   new StorageError({