fix(synapse-sdk): address batching review feedback

Author: hugomrdias

docs/src/content/docs/developer-guides/storage/upload-pipeline.mdx

@@ -55,6 +55,43 @@ The result contains:
 - **`copies`** - array of successful copies, each with `providerId`, `dataSetId`, `pieceId`, `role` (`'primary'` or `'secondary'`), `retrievalUrl`, and `isNewDataSet`
 - **`failedAttempts`** - providers that were tried but did not produce a copy. The SDK retries failed secondaries with alternate providers, so a non-empty array often just means a provider was swapped out. These are diagnostic, check `complete` for the actual outcome.
 
+### Uploading Multiple Files
+
+Piece batching is enabled by default. Compatible uploads that run concurrently can share an on-chain transaction when they use the same provider and data set. Each provider maintains its own batch.
+
+Start the uploads together to give them an opportunity to join the same batch:
+
+```ts
+const results = await Promise.all(
+  files.map((file) => synapse.storage.upload(file))
+)
+```
+
+Sequential uploads cannot share a batch because each call waits for its own on-chain confirmation before the next call starts:
+
+```ts
+for (const file of files) {
+  await synapse.storage.upload(file)
+}
+```
+
+By default, the SDK submits a batch after a zero-delay window. You can instead hold compatible pieces until the transaction size limit is reached or you explicitly flush them:
+
+```ts
+const synapse = Synapse.create({
+  account: privateKeyToAccount("0x..."),
+  pieceBatching: { wait: { kind: "limiter" } },
+})
+
+const uploads = files.map((file) => synapse.storage.upload(file))
+await synapse.storage.flush()
+const results = await Promise.all(uploads)
+```
+
+`flush()` waits for accepted uploads and pulls to finish parking, then submits their pending batch windows. It does not report whether every upload was submitted or confirmed successfully; always await the individual upload promises for results and errors.
+
+Set `pieceBatching: false` when creating `Synapse` to disable batching. Use the [split operations](#split-operations) when you need manual control over provider selection, signing, or each store, pull, and commit phase.
+
 ### Upload with Metadata
 
 Attach metadata to organize uploads. The SDK reuses existing data sets when metadata matches, avoiding duplicate payment rails:

packages/synapse-sdk/src/storage/manager.ts

@@ -198,9 +198,14 @@ export class StorageManager {
    * to determine overall success. Don't use `failedAttempts.length` as a failure
    * signal as `failedAttempts` exists as a diagnostic for intermediate failures.
    *
+   * Batching is enabled by default. Compatible concurrent calls can share
+   * on-chain transactions, while sequentially awaiting each call prevents those
+   * uploads from joining the same batch.
+   *
    * For large files, prefer streaming to minimize memory usage.
    *
-   * For uploading multiple files, use the split operations API directly:
+   * For manual control over providers, signing, or individual phases, use the
+   * split operations API directly:
    * createContexts() -> store() -> presignForCommit() -> pull() -> commit()
    *
    * @param data - Raw bytes (Uint8Array) or ReadableStream to upload
@@ -392,7 +397,15 @@ export class StorageManager {
     }
   }
 
-  /** Flush all piece windows currently accepted by this Synapse instance. */
+  /**
+   * Submit all piece-batch windows currently accepted by this Synapse instance.
+   *
+   * Waits for in-progress uploads and pulls to finish parking before submitting
+   * their pending windows. Resolving does not mean every upload was submitted or
+   * confirmed successfully; failures are reported by the individual upload
+   * promises, which callers must also await. This is a no-op when batching is
+   * disabled.
+   */
   async flush(): Promise<void> {
     await getPieceBatchingService(this._synapse)?.flush()
   }

packages/synapse-sdk/src/storage/piece-batching.ts

@@ -162,15 +162,15 @@ export class PieceBatchingService {
     const key = this.key(context)
     const existing = this.entries.get(key)
     if (existing != null) {
-      void existing.then((entry) => {
+      return existing.then((entry) => {
         const dataSet = entry.batcher.dataSet
         if (dataSet == null) {
           entry.contexts.add(context)
         } else {
           context.syncBatcherDataSet(dataSet.dataSetId, dataSet.clientDataSetId)
         }
+        return entry
       })
-      return existing
     }
 
     const created = this.createEntry(context)

packages/synapse-sdk/src/test/storage-upload.test.ts

@@ -12,6 +12,8 @@ import { setup } from 'iso-web/msw'
 import { HttpResponse, http } from 'msw'
 import { createWalletClient, http as viemHttp } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
+import type { StorageContext } from '../storage/context.ts'
+import { PieceBatchingService } from '../storage/piece-batching.ts'
 import { Synapse } from '../synapse.ts'
 import type { PieceCID } from '../types.ts'
 import { SIZE_CONSTANTS } from '../utils/constants.ts'
@@ -180,6 +182,37 @@ describe('Storage Upload', () => {
     )
   })
 
+  it('should reject concurrent uploads cleanly when shared batch entry creation fails', async () => {
+    const expected = new Error('entry creation failed')
+    let rejectEntry: (error: Error) => void = () => undefined
+    const entryFailure = new Promise<never>((_resolve, reject) => {
+      rejectEntry = reject
+    })
+    const context = {
+      dataSetId: 1n,
+      provider: { id: 1n },
+      getBatcherDataSet: () => entryFailure,
+    } as unknown as StorageContext
+    const batching = new PieceBatchingService(new Synapse({ client, source: null }), {})
+
+    const uploads = [
+      batching.upload(context, { data: new Uint8Array(127) }).committed,
+      batching.upload(context, { data: new Uint8Array(128) }).committed,
+    ]
+    rejectEntry(expected)
+
+    const results = await Promise.allSettled(uploads)
+    assert.deepEqual(
+      results.map((result) => result.status),
+      ['rejected', 'rejected']
+    )
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        assert.strictEqual(result.reason, expected)
+      }
+    }
+  })
+
   it('should expose flush for limiter-based batching', async () => {
     let addPiecesCalls = 0
     const txHash = '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef123456'