@ultimat3/storage 27.0.0 → 27.2.0

package/README.md

@@ -370,7 +370,7 @@ An upload happens **before** the row it belongs to exists, so it lands at
 | `pendingKey(orgId, uploadName(id, filename))` | `org/o1/pending/u-1.png` |
 | `quarantineKey(orgId, name)` | `org/o1/pending/quarantine/u-1.png` |
 | `attachmentKey(orgId, { entity, id, field }, name)` | `org/o1/post/p-1/cover/u-1.png` |
-| `promoteAttachment({ disk, key, orgId, target, policy })` | `stat`, `copy`, then `delete` — never the reverse. **`policy` is required**: the object is measured here (`stat().size` over `policy.maxBytes` is `X_STORAGE_TOO_LARGE`, and it stays under `pending/` for the sweep), because an s3 presign bounds no size. A retry after the source is gone answers the already-attached object instead of `X_STORAGE_NOT_FOUND`. The key must be a **pending** one (`isPendingKey`): an attached key a client sent back is another row's file, and moving it would delete the victim's copy (`X_STORAGE_NOT_PENDING`) |
+| `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`) |
 | `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 |
 
@@ -421,6 +421,7 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_LIST_FAILED` | the disk REFUSED a listing — denied `s3:ListBucket`, a throttle, an unreadable root. An **empty** disk is still not an error |
 | `X_STORAGE_QUARANTINED` | `promoteAttachment` on a key nothing has released from `pending/quarantine/` |
 | `X_STORAGE_NOT_PENDING` | `promoteAttachment` on a key outside the org's `pending/` prefix — most often another row's attached key |
+| `X_STORAGE_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 |
 | `X_STORAGE_READ_FAILED` | the disk REFUSED a `get`/`stat`/`exists`/`stream` or the read half of a `copy` — a denied `s3:GetObject`, a throttle, an unreadable file. An **absent** object is still `X_STORAGE_NOT_FOUND`, including one deleted between the existence check and the read |

package/package.json

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

package/src/attachment.ts

@@ -7,7 +7,8 @@
 import type { Clock } from '@ultimat3/core';
 import { assert, finiteCount, renderThrowable, systemClock } from '@ultimat3/core';
 import type { StorageDriver, StorageListEntry, StorageObject } from './driver';
-import { notPending, objectNotFound, orgMismatch, quarantined, tooLarge } from './errors';
+import { objectNotFound, orgMismatch, tooLarge } from './errors';
+import { alreadyPromoted, notPending, quarantined } from './errors-promote';
 import { isWithinOrg, orgPrefix, scopedKey } from './path';
 import type { UploadPolicy } from './upload';
 
@@ -141,10 +142,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.
  *
- * Idempotent across a retry: a source that is gone with the destination already there answers the
- * destination. Promotion is copy-then-delete inside a request whose row write can still roll back,
- * and the retry used to raise `X_STORAGE_NOT_FOUND` for a file sitting exactly where it belonged.
- * A source that is gone with NO destination is still `X_STORAGE_NOT_FOUND`.
+ * 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,
+ * and its cleanup deleted the FIRST row's bytes. Only the call that moved the bytes may hand them
+ * back; a retry is told where they are and answers the row that holds them. A source that is gone
+ * with NO destination is still `X_STORAGE_NOT_FOUND`.
  *
  * The copy is `disk.copy`, not `get` + `put`: promotion used to download the whole object into
  * this process and upload it again, so attaching a 500MB file moved a gigabyte through the pod
@@ -168,8 +171,9 @@ export async function promoteAttachment(input: PromoteAttachmentInput): Promise<
   const attached = attachmentKey(input.orgId, input.target, name);
   const pending = await disk.stat(input.key);
   if (pending === undefined) {
-    const already = await disk.stat(attached);
-    if (already !== undefined) return already;
+    if ((await disk.stat(attached)) !== undefined) {
+      throw alreadyPromoted(input.key, attached, input.orgId);
+    }
     throw objectNotFound(disk.name, input.key);
   }
   if (pending.size > input.policy.maxBytes) {

package/src/errors-promote.ts

@@ -0,0 +1,44 @@
+// The refusals of the pending → attached move (`promoteAttachment`, `releaseQuarantine`): a key
+// still in quarantine, a key that is not a pending upload, and one an earlier call already moved.
+// Their codes are registered with the rest of the package's in `errors.ts`.
+
+import { StorageError } from './errors';
+
+/**
+ * A key still under the quarantine prefix. The framework never scans bytes — that is the app's
+ * job — so the only thing it can enforce is that nothing leaves quarantine without the app
+ * saying so, which is what `promoteAttachment` refusing this key means.
+ */
+export const quarantined = (key: string, orgId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_QUARANTINED',
+    cause: `"${key}" is still under the quarantine prefix, so nothing has cleared it for use`,
+    fix: `scan the bytes, then releaseQuarantine({ disk, key: '${key}', orgId: '${orgId}' }) — promote the key it returns`,
+    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 pending key is gone and the attached one is there: an earlier call moved these bytes. Never
+ * answered as a success — only the call that moved them may hand them back, because a caller's
+ * cleanup of its own failed write deletes whatever key it was handed, and this one is a row's.
+ */
+export const alreadyPromoted = (key: string, attachedKey: string, orgId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_ALREADY_PROMOTED',
+    cause: `"${key}" was already promoted to "${attachedKey}" by an earlier call (a retried or doubled confirm), so this call moved nothing`,
+    fix: `await disk.stat('${attachedKey}') answers the moved object: answer the row that references that key if one exists, write it with that key if none does, and never delete the key on a failure of your own`,
+    meta: { key, attachedKey, orgId },
+  });

package/src/errors.ts

@@ -31,6 +31,7 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_READ_FAILED',
   'X_STORAGE_OBJECT_LOCKED',
   'X_STORAGE_KEY_UNSHARED',
+  'X_STORAGE_ALREADY_PROMOTED',
 ] as const;
 
 /**
@@ -72,6 +73,7 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_READ_FAILED: 'the object could not be read',
   X_STORAGE_OBJECT_LOCKED: 'the object is under retention or a legal hold',
   X_STORAGE_KEY_UNSHARED: 'object key is outside every tenant and every shared prefix',
+  X_STORAGE_ALREADY_PROMOTED: 'the upload was already promoted onto its row',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -396,32 +398,6 @@ export const listFailed = (
   });
 };
 
-/**
- * A key still under the quarantine prefix. The framework never scans bytes — that is the app's
- * job — so the only thing it can enforce is that nothing leaves quarantine without the app
- * saying so, which is what `promoteAttachment` refusing this key means.
- */
-export const quarantined = (key: string, orgId: string): StorageError =>
-  new StorageError({
-    code: 'X_STORAGE_QUARANTINED',
-    cause: `"${key}" is still under the quarantine prefix, so nothing has cleared it for use`,
-    fix: `scan the bytes, then releaseQuarantine({ disk, key: '${key}', orgId: '${orgId}' }) — promote the key it returns`,
-    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({

package/src/index.ts

@@ -84,7 +84,6 @@ export {
   pathUnsafe,
   putFailed,
   putTooLarge,
-  quarantined,
   readFailed,
   STORAGE_ERROR_CODES,
   STORAGE_ERROR_TITLES,
@@ -97,6 +96,7 @@ export {
   uploadFailed,
   xmlBodyUnreadable,
 } from './errors';
+export { alreadyPromoted, quarantined } from './errors-promote';
 export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
 export type {