fix(spec): describe CompleteUploadRequest.eTag as stored, not compared

.changeset/24648-etag-describe.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/spec': patch
+---
+
+`CompleteUploadRequestSchema.eTag` no longer describes itself as "S3 ETag verification". The upload completion door stores the client-reported value on the file record as sent and compares it with nothing, because no storage adapter reports a stored object's ETag. The description now says so, and names the check the door does run before committing: the storage backend must hold bytes under the file's key and, when the upload declared a size, hold exactly that many. The schema's shape is unchanged.

content/docs/references/api/storage.mdx

@@ -102,7 +102,7 @@ const result = CompleteChunkedUploadRequestSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **fileId** | `string` | ✅ | File ID returned from presigned request |
-| **eTag** | `string` | optional | S3 ETag verification |
+| **eTag** | `string` | optional | ETag the client reports for the uploaded object. Stored on the file record as sent and not compared with anything: no storage adapter reports a stored object's ETag. Before committing, the door checks that the storage backend holds bytes under the file's key and, when the upload declared a size, that the held size equals it. |
 
 
 ---

packages/spec/src/api/storage.zod.ts

@@ -73,7 +73,12 @@ export const GetPresignedUrlRequestSchema = lazySchema(() => z.object({
 
 export const CompleteUploadRequestSchema = lazySchema(() => z.object({
   fileId: z.string().describe('File ID returned from presigned request'),
-  eTag: z.string().optional().describe('S3 ETag verification'),
+  eTag: z.string().optional().describe(
+    'ETag the client reports for the uploaded object. Stored on the file record as sent and not compared '
+    + 'with anything: no storage adapter reports a stored object\'s ETag. Before committing, the door checks '
+    + 'that the storage backend holds bytes under the file\'s key and, when the upload declared a size, '
+    + 'that the held size equals it.',
+  ),
 }));
 
 // ==========================================