@beam-network/sdk 0.2.23 → 0.3.0

package/dist/client.js

@@ -1,6 +1,6 @@
-import { abortMultipartUpload, createMultipartUpload, nowIso, prepareProviderDestination, prepareProviderSource, listPartsPageMarker, listPartsVerifyMarker, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
+import { abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDeleteObject, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signListObjects, signUploadPartCopy } from "./provider-signing.js";
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes } from "./nats-control.js";
-import { directMultipartInitialPartNumber } from "./multipart-limits.js";
+import { multipartPartNumber } from "./multipart-limits.js";
 export { BEAM_DEFAULT_NATS_URL };
 export class BeamApiError extends Error {
     status;
@@ -18,7 +18,6 @@ export class BeamClient {
     fetchImpl;
     control;
     routeSigningConcurrency;
-    recoverySigners = new Map();
     constructor(options = {}) {
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
@@ -42,12 +41,16 @@ export class BeamClient {
         }
     }
     async close() {
-        this.stopAllRecoverySigners();
         return this.control.close();
     }
-    createRawTransfer(input) {
+    openTransferTerminalWaiter(transferId) {
+        validateId(transferId, "transferId");
+        return this.control.openTerminalSignalWaiter(transferId);
+    }
+    async createRawTransfer(input) {
+        const transferId = await transferIdForIdempotencyKey(input.idempotencyKey);
         const body = compact({
-            transfer_id: newTransferId(),
+            transfer_id: transferId,
             sources: input.sources,
             destinations: input.destinations,
             total_size: input.totalSize,
@@ -58,71 +61,105 @@ export class BeamClient {
             callbacks: input.callbacks,
             test_mode: input.testMode || undefined,
             progressive_mode: input.progressiveMode || undefined,
-            signed_url_flow: input.signedUrlFlow
+            signed_url_flow: "signed_url_v2"
+        });
+        return this.control.request("transfer.create", body, {
+            transferId,
+            idempotencyKey: `transfer:${transferId}:create`
         });
-        return this.control.request("transfer.create", body);
     }
     createTransfer(input) {
         return this.prepareProviderTransfer(input);
     }
     transferStatus(transferId) {
         validateId(transferId, "transferId");
-        return this.control.request("transfer.status", { transfer_id: transferId }, transferId);
+        return this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
     }
     distributeTransfer(transferId) {
         validateId(transferId, "transferId");
-        return this.control.request("transfer.distribute", { transfer_id: transferId }, transferId);
+        return this.control.request("transfer.distribute", { transfer_id: transferId }, {
+            transferId,
+            idempotencyKey: `transfer:${transferId}:distribute`
+        });
     }
     async cancelTransfer(transferId) {
         validateId(transferId, "transferId");
-        try {
-            return await this.control.request("transfer.cancel", { transfer_id: transferId }, transferId);
-        }
-        finally {
-            this.stopRecoverySigner(transferId);
-        }
+        const result = await this.control.request("transfer.cancel", { transfer_id: transferId }, {
+            transferId,
+            idempotencyKey: `transfer:${transferId}:cancel`
+        });
+        return result;
     }
-    planTransfer(input) {
-        return this.control.request("transfer.plan", compact({
+    async planTransfer(input) {
+        const result = await this.control.request("transfer.plan", compact({
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
             test_mode: input.testMode || undefined,
             urls_expires_at: input.urlsExpiresAt,
-            signed_url_flow: input.signedUrlFlow
+            signed_url_flow: "signed_url_v2"
         }));
+        if (result.success)
+            validateCompactTransferPlan(result.plan_descriptor, result.signed_url_flow);
+        return result;
     }
-    prepareTransfer(input) {
-        const transferId = newTransferId();
-        return this.control.request("transfer.prepare", compact({
+    async prepareTransfer(input) {
+        const transferId = await transferIdForIdempotencyKey(input.idempotencyKey);
+        const result = await this.control.request("transfer.prepare", compact({
             transfer_id: transferId,
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
             test_mode: input.testMode || undefined,
             urls_expires_at: input.urlsExpiresAt,
-            signed_url_flow: input.signedUrlFlow
-        }), transferId);
+            signed_url_flow: "signed_url_v2"
+        }), {
+            transferId,
+            idempotencyKey: `transfer:${transferId}:prepare`
+        });
+        if (result.success)
+            validateCompactTransferPlan(result.plan_descriptor, result.signed_url_flow);
+        return result;
     }
     async attachSignedUrls(transferId, input) {
         validateId(transferId, "transferId");
+        validateMultipartGroupManifest(input.multipartGroupManifest, transferId);
+        validateSignedRouteManifestContract(input.chunkRoutes, input.multipartGroupManifest);
+        const destinationCount = new Set(input.chunkRoutes.map((route) => route.destination_id)).size;
+        const orderedRoutes = input.chunkRoutes
+            .map((route) => {
+            if (signedRouteDeliveryIndex(route) !== undefined)
+                return route;
+            if (destinationCount !== 1) {
+                throw new Error("delivery_index is required when manually attaching routes for multiple destinations");
+            }
+            return { ...route, delivery_index: route.chunk_index };
+        })
+            .sort(compareSignedRoutesByDelivery);
+        const streamId = await stableRouteStreamId({
+            transferId,
+            planIdentity: await routeCoordinateChecksum(orderedRoutes),
+            totalRoutes: orderedRoutes.length,
+            totalChunks: countDistinctRouteChunks(orderedRoutes)
+        });
         const stream = new RouteStreamSender(this.control, {
+            streamId,
             transferId,
-            totalRoutes: input.chunkRoutes.length,
-            totalChunks: countDistinctRouteChunks(input.chunkRoutes),
+            totalRoutes: orderedRoutes.length,
+            totalChunks: countDistinctRouteChunks(orderedRoutes),
             urlsExpiresAt: input.urlsExpiresAt,
-            signedUrlFlow: input.signedUrlFlow ?? "signed_url_v1",
+            multipartGroupManifest: input.multipartGroupManifest,
             autoDistribute: input.autoDistribute ?? true
         });
         await stream.begin();
-        for (const route of input.chunkRoutes) {
+        for (const route of orderedRoutes) {
             stream.addRoute(route);
         }
         return stream.complete();
     }
     async prepareProviderTransfer(input) {
         const expiresIn = input.expiresIn ?? 3600;
-        const requestedSignedUrlFlow = input.signedUrlFlow ?? "signed_url_v1";
+        const requestedSignedUrlFlow = "signed_url_v2";
         const preparedDestinations = input.destinations.map((destination, index) => prepareProviderDestination(destination, { index }));
         const destinationsById = new Map();
         preparedDestinations.forEach((preparedDestination, index) => {
@@ -141,7 +178,8 @@ export class BeamClient {
             destinations: preparedDestinations,
             name: input.name,
             testMode: input.testMode,
-            signedUrlFlow: requestedSignedUrlFlow
+            signedUrlFlow: requestedSignedUrlFlow,
+            idempotencyKey: input.idempotencyKey
         });
         if (!prepared.success) {
             return prepared;
@@ -156,38 +194,44 @@ export class BeamClient {
             }
             sourcesById.set(preparedSource.source_id, source);
         });
-        const signedUrlFlow = prepared.signed_url_flow ?? requestedSignedUrlFlow;
-        const routeStream = new RouteStreamSender(this.control, {
-            transferId: prepared.transfer_id,
-            totalRoutes: prepared.plan_descriptor.delivery_route_count,
-            totalChunks: prepared.plan_descriptor.logical_chunk_count,
-            signedUrlFlow,
-            autoDistribute: input.distribute !== false
-        });
         const multipartUploads = new Map();
-        const multipartUploadPromises = new Map();
-        await this.startProviderRouteRecoverySigner({
-            prepared,
-            sourcesById,
-            destinationsById,
-            multipartUploads,
-            expiresIn,
-            signedUrlFlow
-        });
-        let routeStreamStarted = false;
+        const pendingRoutes = new Set();
+        let routeStream = null;
+        let routeStreamBeginAttempted = false;
         try {
+            const multipartGroupManifest = await createMultipartGroupManifest({
+                prepared,
+                destinationsById,
+                multipartUploads,
+                expiresIn,
+                concurrency: this.routeSigningConcurrency
+            });
+            validateMultipartGroupManifest(multipartGroupManifest, prepared.transfer_id);
+            const streamId = await stableRouteStreamId({
+                transferId: prepared.transfer_id,
+                planIdentity: prepared.plan_descriptor.plan_nonce,
+                totalRoutes: prepared.plan_descriptor.delivery_route_count,
+                totalChunks: prepared.plan_descriptor.logical_chunk_count
+            });
+            routeStream = new RouteStreamSender(this.control, {
+                streamId,
+                transferId: prepared.transfer_id,
+                totalRoutes: prepared.plan_descriptor.delivery_route_count,
+                totalChunks: prepared.plan_descriptor.logical_chunk_count,
+                multipartGroupManifest,
+                autoDistribute: input.distribute !== false
+            });
+            routeStreamBeginAttempted = true;
             await routeStream.begin();
-            routeStreamStarted = true;
-            const pendingRoutes = [];
-            const flushOldestRoute = async () => {
-                const pending = pendingRoutes.shift();
-                if (pending)
-                    routeStream.addRoute(await pending);
+            const streamNextCompletedRoute = async () => {
+                const settled = await Promise.race([...pendingRoutes].map((pending) => pending.then((route) => ({ pending, route }))));
+                pendingRoutes.delete(settled.pending);
+                routeStream.addRoute(settled.route);
             };
-            for (const chunk of materializePlanChunks(prepared.plan_descriptor)) {
+            for (const chunk of materializePlanChunks(prepared.plan_descriptor, prepared.transfer_id)) {
                 await input.throwIfCancelled?.(prepared.transfer_id);
                 for (const target of chunk.destinations) {
-                    pendingRoutes.push((async () => {
+                    const pendingRoute = (async () => {
                         await input.throwIfCancelled?.(prepared.transfer_id);
                         const destination = destinationsById.get(target.destination_id);
                         if (!destination)
@@ -199,74 +243,47 @@ export class BeamClient {
                         const finalObjectKey = typeof metadata.final_object_key === "string" ? metadata.final_object_key : target.object_key;
                         if (!finalObjectKey)
                             throw new Error("destination signing target is missing object_key");
-                        const multipartKey = `${prepared.transfer_id}:${target.destination_id}:${chunk.source_id}:${finalObjectKey}`;
-                        let uploadPromise = multipartUploadPromises.get(multipartKey);
-                        if (!uploadPromise) {
-                            uploadPromise = (async () => {
-                                const multipartCreatedAt = nowIso();
-                                const upload = isHippiusDestination(destination)
-                                    ? {
-                                        destination,
-                                        objectKey: finalObjectKey,
-                                        uploadId: "",
-                                        completeUrl: "",
-                                        abortUrl: "",
-                                        listUrl: "",
-                                        multipartGroupId: multipartKey,
-                                        multipartCreatedAt
-                                    }
-                                    : await (async () => {
-                                        const uploadId = await createMultipartUpload(destination, finalObjectKey);
-                                        return {
-                                            destination,
-                                            objectKey: finalObjectKey,
-                                            uploadId,
-                                            completeUrl: await signCompleteMultipartUpload(destination, finalObjectKey, uploadId, expiresIn),
-                                            abortUrl: await signAbortMultipartUpload(destination, finalObjectKey, uploadId, expiresIn),
-                                            listUrl: await signListMultipartUpload(destination, finalObjectKey, uploadId, expiresIn),
-                                            multipartGroupId: multipartKey,
-                                            multipartCreatedAt
-                                        };
-                                    })();
-                                multipartUploads.set(multipartKey, upload);
-                                return upload;
-                            })();
-                            multipartUploadPromises.set(multipartKey, uploadPromise);
+                        const upload = multipartUploads.get(multipartGroupStateKey(prepared.transfer_id, target.destination_id, chunk.source_id, finalObjectKey));
+                        if (!isHippiusDestination(destination) && !upload) {
+                            throw new Error(`multipart group manifest is missing for ${chunk.source_id}:${target.destination_id}`);
                         }
-                        const upload = await uploadPromise;
                         return this.signProviderRoute({
                             chunk,
                             target,
                             source,
                             destination,
                             expiresIn,
-                            upload,
+                            ...(upload ? { upload } : {}),
                             transferId: prepared.transfer_id,
                             finalObjectKey,
                             partNumber: typeof metadata.part_number === "number"
                                 ? metadata.part_number
-                                : directMultipartInitialPartNumber(chunk.chunk_index),
-                            signedUrlFlow
+                                : multipartPartNumber(chunk.source_chunk_index),
                         });
-                    })());
-                    if (pendingRoutes.length >= this.routeSigningConcurrency)
-                        await flushOldestRoute();
+                    })();
+                    pendingRoutes.add(pendingRoute);
+                    if (pendingRoutes.size >= this.routeSigningConcurrency)
+                        await streamNextCompletedRoute();
                 }
             }
-            while (pendingRoutes.length)
-                await flushOldestRoute();
+            while (pendingRoutes.size)
+                await streamNextCompletedRoute();
             const attached = await routeStream.complete();
             if (!attached.success) {
                 throw new Error(attached.error ?? attached.message ?? "route stream failed");
             }
         }
         catch (error) {
-            routeStream.abort();
-            this.stopRecoverySigner(prepared.transfer_id);
-            await abortCreatedUploads(multipartUploads);
-            if (routeStreamStarted) {
-                await cancelTransferAfterRouteStreamFailure(this, prepared.transfer_id, error);
-            }
+            if (routeStream)
+                await routeStream.abort();
+            await Promise.allSettled(pendingRoutes);
+            await cancelAndAbortProviderFailure({
+                client: this,
+                transferId: prepared.transfer_id,
+                cause: error,
+                uploads: multipartUploads,
+                abortBeforeCancel: !routeStreamBeginAttempted
+            });
             throw error;
         }
         return prepared;
@@ -275,43 +292,17 @@ export class BeamClient {
         if (isHippiusDestination(input.destination)) {
             return signDestinationRoute({
                 chunk: input.chunk,
-                target: input.target,
-                source: input.source,
-                destination: input.destination,
-                expiresIn: input.expiresIn,
-                transferId: input.transferId,
-                multipartGroupId: input.upload.multipartGroupId,
-                multipartCreatedAt: input.upload.multipartCreatedAt,
-                fetchImpl: this.fetchImpl
-            });
-        }
-        if (!input.target.object_key) {
-            throw new Error("destination signing target is missing object_key");
-        }
-        if (input.signedUrlFlow === "signed_url_v1") {
-            const partVerifyUrl = await signListMultipartUpload(input.destination, input.finalObjectKey, input.upload.uploadId, input.expiresIn, { maxParts: 1, partNumberMarker: listPartsVerifyMarker(input.partNumber) });
-            const listPageUrl = await signListMultipartUpload(input.destination, input.finalObjectKey, input.upload.uploadId, input.expiresIn, { maxParts: 1000, partNumberMarker: listPartsPageMarker(input.partNumber) });
-            return signDestinationRoute({
-                chunk: input.chunk,
-                target: input.target,
+                target: { ...input.target, metadata: partRouteMetadata(input.target.metadata) },
                 source: input.source,
                 destination: input.destination,
                 expiresIn: input.expiresIn,
-                uploadId: input.upload.uploadId,
-                partNumber: input.partNumber,
-                multipartObjectKey: input.finalObjectKey,
-                completeUrl: input.upload.completeUrl,
-                abortUrl: input.upload.abortUrl,
-                listUrl: input.upload.listUrl,
-                partVerifyUrl,
-                listPageUrl,
-                transferId: input.transferId,
-                multipartGroupId: input.upload.multipartGroupId,
-                multipartCreatedAt: input.upload.multipartCreatedAt,
-                commitMethod: "upload_part",
                 fetchImpl: this.fetchImpl
             });
         }
+        const upload = input.upload;
+        if (!upload)
+            throw new Error("signed_url_v2 route is missing its multipart group");
+        validateMultipartPartNumber(input.partNumber, upload.manifest);
         const stagingObjectPrefix = buildStagingObjectPrefix({
             finalObjectKey: input.finalObjectKey,
             transferId: input.transferId,
@@ -323,27 +314,20 @@ export class BeamClient {
             `part-${input.partNumber}-chunk-${input.chunk.chunk_index}`
         ].join("/");
         const copySourceRange = `bytes=0-${Math.max(0, input.chunk.chunk_size - 1)}`;
-        const { copyUrl, copySource } = await signUploadPartCopy(input.destination, input.finalObjectKey, stagingObjectKey, input.upload.uploadId, input.partNumber, input.expiresIn, copySourceRange);
-        const stagingListUrl = await signListObjects(input.destination, stagingObjectPrefix, input.expiresIn);
-        const deleteUrl = await signDeleteObject(input.destination, stagingObjectKey, input.expiresIn);
+        const [{ copyUrl, copySource }, deleteUrl] = await Promise.all([
+            signUploadPartCopy(input.destination, input.finalObjectKey, stagingObjectKey, upload.uploadId, input.partNumber, input.expiresIn, copySourceRange),
+            signDeleteObject(input.destination, stagingObjectKey, input.expiresIn)
+        ]);
         return signDestinationRoute({
             chunk: input.chunk,
-            target: input.target,
+            target: { ...input.target, metadata: partRouteMetadata(input.target.metadata) },
             source: input.source,
             destination: input.destination,
             expiresIn: input.expiresIn,
-            uploadId: input.upload.uploadId,
             partNumber: input.partNumber,
-            multipartObjectKey: input.finalObjectKey,
-            completeUrl: input.upload.completeUrl,
-            abortUrl: input.upload.abortUrl,
-            listUrl: input.upload.listUrl,
-            transferId: input.transferId,
-            multipartGroupId: input.upload.multipartGroupId,
-            multipartCreatedAt: input.upload.multipartCreatedAt,
+            multipartGroupId: upload.manifest.multipart_group_id,
             commitMethod: "upload_part_copy",
             stagingObjectKey,
-            stagingListUrl,
             copyUrl,
             copySource,
             copySourceRange,
@@ -351,79 +335,6 @@ export class BeamClient {
             fetchImpl: this.fetchImpl
         });
     }
-    async startProviderRouteRecoverySigner(input) {
-        this.stopRecoverySigner(input.prepared.transfer_id);
-        const stop = await this.control.serveRouteRecoverySigner(input.prepared.transfer_id, async (payload) => {
-            const routes = await mapOrderedWithConcurrency(payload.chunks, this.routeSigningConcurrency, async (requested) => {
-                const chunk = materializePlanChunk(input.prepared.plan_descriptor, requested.source_id, requested.chunk_index);
-                if (!chunk) {
-                    throw new Error(`recovery signing chunk not found: ${requested.source_id}:${requested.chunk_index}`);
-                }
-                const target = chunk.destinations.find((candidate) => candidate.destination_id === requested.destination_id);
-                if (!target) {
-                    throw new Error(`recovery signing destination not found: ${requested.destination_id}`);
-                }
-                const source = input.sourcesById.get(requested.source_id);
-                const destination = input.destinationsById.get(requested.destination_id);
-                if (!source || !destination) {
-                    throw new Error("recovery signing provider configuration missing");
-                }
-                const upload = input.multipartUploads.get(requested.multipart_group_id) ?? input.multipartUploads.get(`${input.prepared.transfer_id}:${requested.destination_id}:${requested.source_id}:${requested.final_object_key}`);
-                if (!upload) {
-                    throw new Error(`recovery signing multipart upload state missing for ${requested.multipart_group_id}`);
-                }
-                const metadata = {
-                    ...(target.metadata ?? {}),
-                    ...(requested.destination_metadata ?? {}),
-                    transfer_id: input.prepared.transfer_id,
-                    final_object_key: requested.final_object_key,
-                    upload_id: requested.upload_id ?? upload.uploadId,
-                    multipart_group_id: requested.multipart_group_id,
-                    multipart_created_at: requested.multipart_created_at ?? upload.multipartCreatedAt,
-                    delivery_index: requested.delivery_index,
-                    part_number: requested.part_number,
-                    logical_attempt_index: requested.logical_attempt_index,
-                    attempt_slot: requested.attempt_slot,
-                    route_generation_id: requested.route_generation_id
-                };
-                return this.signProviderRoute({
-                    chunk,
-                    target: {
-                        ...target,
-                        object_key: target.object_key ?? requested.final_object_key,
-                        metadata
-                    },
-                    source,
-                    destination,
-                    expiresIn: input.expiresIn,
-                    upload,
-                    transferId: input.prepared.transfer_id,
-                    finalObjectKey: requested.final_object_key,
-                    partNumber: requested.part_number,
-                    signedUrlFlow: input.signedUrlFlow
-                });
-            });
-            return {
-                transfer_id: payload.transfer_id,
-                route_generation_id: payload.route_generation_id,
-                signed_at: nowIso(),
-                route_batch: compactSignedRoutes(routes)
-            };
-        });
-        this.recoverySigners.set(input.prepared.transfer_id, stop);
-    }
-    stopRecoverySigner(transferId) {
-        const stop = this.recoverySigners.get(transferId);
-        if (!stop)
-            return;
-        stop();
-        this.recoverySigners.delete(transferId);
-    }
-    stopAllRecoverySigners() {
-        for (const transferId of [...this.recoverySigners.keys()]) {
-            this.stopRecoverySigner(transferId);
-        }
-    }
     async createAndDistribute(input) {
         const transfer = await this.createRawTransfer(input);
         if (transfer.success) {
@@ -433,37 +344,95 @@ export class BeamClient {
     }
     async waitForTransfer(transferId, options = {}) {
         const timeoutMs = options.timeoutMs ?? 300_000;
-        const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+        const pollIntervalMs = options.pollIntervalMs ?? 15_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new Error("timeoutMs must be a positive number.");
+        }
+        if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+            throw new Error("pollIntervalMs must be a positive number.");
+        }
+        const configuredMaxPollIntervalMs = options.maxPollIntervalMs ?? 30_000;
+        if (!Number.isFinite(configuredMaxPollIntervalMs) || configuredMaxPollIntervalMs <= 0) {
+            throw new Error("maxPollIntervalMs must be a positive number.");
+        }
+        const maxPollIntervalMs = Math.max(pollIntervalMs, configuredMaxPollIntervalMs);
         const startedAt = Date.now();
-        while (true) {
-            const status = await this.transferStatus(transferId);
-            if (status.status === "completed") {
-                this.stopRecoverySigner(transferId);
-                return status;
-            }
-            if (status.status === "failed") {
-                this.stopRecoverySigner(transferId);
-                throw new Error(`Transfer failed: ${status.error_message ?? "unknown error"}`);
-            }
-            if (status.status === "cancelled") {
-                this.stopRecoverySigner(transferId);
-                throw new Error("Transfer cancelled");
+        let currentPollIntervalMs = pollIntervalMs;
+        let terminalWaiter = null;
+        try {
+            terminalWaiter = await this.openTransferTerminalWaiter(transferId);
+        }
+        catch {
+            // Terminal delivery is advisory; authoritative status remains available.
+        }
+        try {
+            while (true) {
+                const status = await this.transferStatus(transferId);
+                if (status.status === "completed") {
+                    return status;
+                }
+                if (status.status === "failed") {
+                    throw new Error(`Transfer failed: ${status.error_message ?? "unknown error"}`);
+                }
+                if (status.status === "cancelled") {
+                    throw new Error("Transfer cancelled");
+                }
+                if (Date.now() - startedAt >= timeoutMs) {
+                    throw new Error(`Transfer ${transferId} did not complete within ${timeoutMs}ms`);
+                }
+                const remainingMs = timeoutMs - (Date.now() - startedAt);
+                const waitMs = Math.min(Math.max(1, remainingMs), jitteredDelay(currentPollIntervalMs));
+                let terminalEvent = null;
+                if (terminalWaiter) {
+                    const waitStartedAt = Date.now();
+                    try {
+                        terminalEvent = await terminalWaiter.wait(waitMs);
+                    }
+                    catch {
+                        try {
+                            await terminalWaiter.close();
+                        }
+                        catch {
+                            // The status fallback remains authoritative even if unsubscribe fails.
+                        }
+                        terminalWaiter = null;
+                        const remainingWaitMs = Math.max(0, waitMs - (Date.now() - waitStartedAt));
+                        if (remainingWaitMs > 0) {
+                            await new Promise((resolve) => setTimeout(resolve, remainingWaitMs));
+                        }
+                    }
+                }
+                else {
+                    await new Promise((resolve) => setTimeout(resolve, waitMs));
+                }
+                if (terminalEvent)
+                    currentPollIntervalMs = pollIntervalMs;
+                else
+                    currentPollIntervalMs = Math.min(maxPollIntervalMs, Math.ceil(currentPollIntervalMs * 1.5));
             }
-            if (Date.now() - startedAt >= timeoutMs) {
-                throw new Error(`Transfer ${transferId} did not complete within ${timeoutMs}ms`);
+        }
+        finally {
+            if (terminalWaiter) {
+                try {
+                    await terminalWaiter.close();
+                }
+                catch {
+                    // Terminal delivery is advisory; closing the client remains the final cleanup boundary.
+                }
             }
-            await sleep(pollIntervalMs);
         }
     }
 }
-const ROUTE_STREAM_BOOTSTRAP_BATCH_ROUTES = 256;
-const ROUTE_STREAM_STEADY_BATCH_ROUTES = 2_048;
+const ROUTE_STREAM_BOOTSTRAP_BATCH_ROUTES = 32;
+const ROUTE_STREAM_STEADY_BATCH_ROUTES = 256;
 class RouteStreamSender {
     control;
     options;
-    streamId = newTransferId();
+    streamId;
     checksum = new RouteKeysChecksum();
     batch = [];
+    pendingRoutes = new Map();
+    nextDeliveryIndex = 0;
     batchIndex = 0;
     routeCount = 0;
     sendTail = Promise.resolve();
@@ -471,6 +440,7 @@ class RouteStreamSender {
     constructor(control, options) {
         this.control = control;
         this.options = options;
+        this.streamId = options.streamId;
     }
     async begin() {
         await this.control.request("transfer.route_stream.begin", compact({
@@ -478,25 +448,48 @@ class RouteStreamSender {
             stream_id: this.streamId,
             total_routes: this.options.totalRoutes,
             total_chunks: this.options.totalChunks,
+            route_contract_version: "signed_url_v2",
+            multipart_group_manifest: this.options.multipartGroupManifest,
             urls_expires_at: this.options.urlsExpiresAt,
-            signed_url_flow: this.options.signedUrlFlow,
+            signed_url_flow: "signed_url_v2",
             auto_distribute: this.options.autoDistribute
-        }), this.options.transferId);
+        }), {
+            transferId: this.options.transferId,
+            idempotencyKey: `transfer:${this.options.transferId}:route-stream:${this.streamId}:begin`
+        });
     }
     addRoute(route) {
-        const normalizedRoute = route.delivery_index === undefined
-            ? { ...route, delivery_index: this.routeCount }
-            : route;
+        const deliveryIndex = signedRouteDeliveryIndex(route);
+        if (deliveryIndex === undefined) {
+            throw new Error("route delivery_index is required");
+        }
+        if (!Number.isSafeInteger(deliveryIndex) || deliveryIndex < 0 || deliveryIndex >= this.options.totalRoutes) {
+            throw new Error(`route delivery_index ${deliveryIndex} is outside the declared route stream`);
+        }
+        if (deliveryIndex < this.nextDeliveryIndex || this.pendingRoutes.has(deliveryIndex)) {
+            throw new Error(`duplicate route delivery_index ${deliveryIndex}`);
+        }
+        this.pendingRoutes.set(deliveryIndex, route);
         this.routeCount += 1;
-        this.batch.push(normalizedRoute);
-        const target = this.batchIndex === 0
-            ? ROUTE_STREAM_BOOTSTRAP_BATCH_ROUTES
-            : ROUTE_STREAM_STEADY_BATCH_ROUTES;
-        if (this.batch.length >= target) {
-            this.enqueueFlush();
+        while (this.pendingRoutes.has(this.nextDeliveryIndex)) {
+            const next = this.pendingRoutes.get(this.nextDeliveryIndex);
+            this.pendingRoutes.delete(this.nextDeliveryIndex);
+            this.batch.push({ ...next, delivery_index: this.nextDeliveryIndex });
+            this.nextDeliveryIndex += 1;
+            const target = this.batchIndex === 0
+                ? ROUTE_STREAM_BOOTSTRAP_BATCH_ROUTES
+                : ROUTE_STREAM_STEADY_BATCH_ROUTES;
+            if (this.batch.length >= target) {
+                this.enqueueFlush();
+            }
         }
     }
     async complete() {
+        if (this.routeCount !== this.options.totalRoutes ||
+            this.pendingRoutes.size !== 0 ||
+            this.nextDeliveryIndex !== this.options.totalRoutes) {
+            throw new Error(`route stream has non-contiguous delivery indices: received ${this.routeCount} of ${this.options.totalRoutes} routes`);
+        }
         this.enqueueFlush();
         await this.sendTail;
         if (this.sendError)
@@ -507,7 +500,10 @@ class RouteStreamSender {
             expected_batches: this.batchIndex,
             expected_routes: this.options.totalRoutes,
             route_keys_checksum: this.checksum.value()
-        }, this.options.transferId);
+        }, {
+            transferId: this.options.transferId,
+            idempotencyKey: `transfer:${this.options.transferId}:route-stream:${this.streamId}:complete`
+        });
     }
     enqueueFlush() {
         if (!this.batch.length)
@@ -529,15 +525,21 @@ class RouteStreamSender {
                     const chunkChecksum = new RouteKeysChecksum();
                     await chunkChecksum.addMany(chunk.map(routeKeyForSignedRoute));
                     this.checksum.merge(chunkChecksum);
+                    const routeChecksum = chunkChecksum.value();
+                    const coordinateChecksum = await routeCoordinateChecksum(chunk);
+                    const batchId = `${this.streamId}:${batchIndex}:${coordinateChecksum}`;
                     await this.control.request("transfer.route_stream.batch", {
                         transfer_id: this.options.transferId,
                         stream_id: this.streamId,
-                        batch_id: `${this.streamId}:${batchIndex}`,
+                        batch_id: batchId,
                         batch_index: batchIndex,
                         route_batch: compactSignedRoutes(chunk),
                         route_count: chunk.length,
-                        route_keys_checksum: chunkChecksum.value()
-                    }, this.options.transferId);
+                        route_keys_checksum: routeChecksum
+                    }, {
+                        transferId: this.options.transferId,
+                        idempotencyKey: `transfer:${this.options.transferId}:route-stream:${this.streamId}:batch:${batchIndex}:${coordinateChecksum}`
+                    });
                 }
                 catch (error) {
                     this.sendError = error;
@@ -545,8 +547,9 @@ class RouteStreamSender {
             });
         }
     }
-    abort() {
+    async abort() {
         this.sendError ??= new Error("route_stream_aborted");
+        await this.sendTail;
     }
 }
 class RouteKeysChecksum {
@@ -574,13 +577,40 @@ class RouteKeysChecksum {
 function routeKeyForSignedRoute(route) {
     return `${route.source_id}:${route.destination_id}:${route.chunk_index}`;
 }
+function signedRouteDeliveryIndex(route) {
+    const metadataIndex = route.metadata?.delivery_index;
+    if (typeof metadataIndex === "number")
+        return metadataIndex;
+    return route.delivery_index;
+}
+function compareSignedRoutesByDelivery(left, right) {
+    const leftIndex = signedRouteDeliveryIndex(left);
+    const rightIndex = signedRouteDeliveryIndex(right);
+    if (leftIndex !== undefined && rightIndex !== undefined && leftIndex !== rightIndex) {
+        return leftIndex - rightIndex;
+    }
+    return routeKeyForSignedRoute(left).localeCompare(routeKeyForSignedRoute(right));
+}
+async function routeCoordinateChecksum(routes) {
+    const checksum = new RouteKeysChecksum();
+    await checksum.addMany(routes.map((route) => `${routeKeyForSignedRoute(route)}:${signedRouteDeliveryIndex(route) ?? "missing"}`));
+    return checksum.value();
+}
+async function stableRouteStreamId(input) {
+    const digest = await sha256Bytes(`beam:route-stream:signed_url_v2:${input.transferId}:${input.planIdentity}:${input.totalRoutes}:${input.totalChunks}`);
+    const bytes = digest.slice(0, 16);
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const value = hex(bytes);
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
 function countDistinctRouteChunks(routes) {
     return new Set(routes.map((route) => `${route.source_id}:${route.chunk_index}`)).size;
 }
-function* materializePlanChunks(descriptor) {
+function* materializePlanChunks(descriptor, transferId) {
     for (const source of descriptor.sources) {
         for (let sourceChunkIndex = 0; sourceChunkIndex < source.chunk_count; sourceChunkIndex += 1) {
-            yield materializePlanChunk(descriptor, source.source_id, source.global_chunk_start + sourceChunkIndex);
+            yield materializePlanChunk(descriptor, transferId, source.source_id, source.global_chunk_start + sourceChunkIndex);
         }
     }
 }
@@ -604,7 +634,7 @@ function positiveInteger(value, label) {
         throw new Error(`${label} must be a positive integer.`);
     return value;
 }
-function materializePlanChunk(descriptor, sourceId, chunkIndex) {
+function materializePlanChunk(descriptor, transferId, sourceId, chunkIndex) {
     const source = descriptor.sources.find((candidate) => candidate.source_id === sourceId);
     if (!source)
         throw new Error(`plan source not found: ${sourceId}`);
@@ -626,15 +656,26 @@ function materializePlanChunk(descriptor, sourceId, chunkIndex) {
             if (!finalObjectKey)
                 throw new Error(`plan final object key not found: ${sourceId}:${destination.destination_id}`);
             const deliveryIndex = chunkIndex * descriptor.destinations.length + destination.destination_index;
+            const partNumber = multipartPartNumber(sourceChunkIndex);
+            const objectKey = destination.provider.toLowerCase() === "hippius"
+                ? `${finalObjectKey}/${descriptor.plan_nonce}/chunk-${String(sourceChunkIndex).padStart(6, "0")}`
+                : buildStagingObjectKey({
+                    finalObjectKey,
+                    transferId,
+                    sourceId,
+                    destinationId: destination.destination_id,
+                    chunkIndex,
+                    partNumber
+                });
             return {
                 destination_id: destination.destination_id,
                 delivery_index: deliveryIndex,
                 provider: destination.provider,
-                object_key: `${finalObjectKey}/${descriptor.plan_nonce}/chunk-${String(sourceChunkIndex).padStart(6, "0")}`,
+                object_key: objectKey,
                 metadata: {
                     ...(destination.metadata ?? {}),
                     final_object_key: finalObjectKey,
-                    part_number: directMultipartInitialPartNumber(chunkIndex),
+                    part_number: partNumber,
                     logical_attempt_index: 0,
                     attempt_slot: 0,
                     route_generation_id: `initial-${chunkIndex}-${destination.destination_id}`,
@@ -655,33 +696,387 @@ async function sha256Bytes(value) {
 function hex(bytes) {
     return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
-async function cancelTransferAfterRouteStreamFailure(client, transferId, cause) {
+async function cancelTransferAfterProviderFailure(client, transferId, cause) {
     try {
-        await client.cancelTransfer(transferId);
+        const result = await client.cancelTransfer(transferId);
+        if (!result.success) {
+            throw new Error(result.message ?? `Beam rejected cancellation for ${transferId}`);
+        }
     }
     catch (cancelError) {
-        throw new Error(`route streaming failed (${errorMessage(cause)}) and transfer cancellation failed (${errorMessage(cancelError)})`);
+        throw new Error(`provider transfer failed (${errorMessage(cause)}) and transfer cancellation failed (${errorMessage(cancelError)})`);
+    }
+}
+async function cancelAndAbortProviderFailure(input) {
+    let cleanupError;
+    let cleanupFailed = false;
+    let cancelError;
+    if (input.abortBeforeCancel) {
+        try {
+            await abortCreatedUploads(input.uploads);
+        }
+        catch (error) {
+            cleanupError = error;
+            cleanupFailed = true;
+        }
+    }
+    try {
+        await cancelTransferAfterProviderFailure(input.client, input.transferId, input.cause);
+    }
+    catch (error) {
+        cancelError = error;
+    }
+    if (!input.abortBeforeCancel || cleanupFailed) {
+        try {
+            await abortCreatedUploads(input.uploads);
+            cleanupError = undefined;
+            cleanupFailed = false;
+        }
+        catch (error) {
+            cleanupError = error;
+            cleanupFailed = true;
+        }
+    }
+    if (cancelError && cleanupFailed) {
+        throw new AggregateError([input.cause, cancelError, cleanupError], `provider transfer, transfer cancellation, and multipart cleanup failed for ${input.transferId}`);
+    }
+    if (cancelError)
+        throw cancelError;
+    if (cleanupFailed) {
+        throw new AggregateError([input.cause, cleanupError], `provider transfer failed and multipart cleanup failed for ${input.transferId}`);
     }
 }
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-function newTransferId() {
+async function createMultipartGroupManifest(input) {
+    const groups = input.prepared.plan_descriptor.sources.flatMap((source) => input.prepared.plan_descriptor.destinations.map((destination) => ({ source, destination })));
+    const results = await mapOrderedWithConcurrency(groups, input.concurrency, async ({ source, destination }) => {
+        try {
+            const destinationConfig = input.destinationsById.get(destination.destination_id);
+            if (!destinationConfig) {
+                throw new Error(`BeamCore returned unknown destination_id: ${destination.destination_id}`);
+            }
+            if (isHippiusDestination(destinationConfig)) {
+                return { ok: true, state: null };
+            }
+            const finalObjectKey = destination.final_object_keys[source.source_id];
+            if (!finalObjectKey) {
+                throw new Error(`plan final object key not found: ${source.source_id}:${destination.destination_id}`);
+            }
+            const multipartGroupId = multipartGroupStateKey(input.prepared.transfer_id, destination.destination_id, source.source_id, finalObjectKey);
+            const finalObjectMetadata = {
+                "beam-transfer-id": input.prepared.transfer_id,
+                "beam-multipart-group-id": multipartGroupId
+            };
+            const uploadId = await createMultipartUpload({
+                destination: destinationConfig,
+                objectKey: finalObjectKey,
+                metadata: finalObjectMetadata
+            });
+            try {
+                const urlsExpiresAt = expiresAtIso(input.expiresIn);
+                const stagingObjectPrefix = buildStagingObjectPrefix({
+                    finalObjectKey,
+                    transferId: input.prepared.transfer_id,
+                    sourceId: source.source_id,
+                    destinationId: destination.destination_id
+                });
+                const stagingListPrefix = `${stagingObjectPrefix}/`;
+                const maxPartNumber = multipartMaxPartNumber(source.chunk_count);
+                const listPageMarkers = multipartListPageMarkers(maxPartNumber);
+                const stagingObjectKeys = multipartStagingObjectKeys({
+                    finalObjectKey,
+                    transferId: input.prepared.transfer_id,
+                    sourceId: source.source_id,
+                    destinationId: destination.destination_id,
+                    globalChunkStart: source.global_chunk_start,
+                    chunkCount: source.chunk_count
+                });
+                const stagingListStartAfter = pagedListStartAfter(stagingObjectKeys);
+                const [completeUrl, abortUrl, listPageUrls, stagingListUrls, finalHeadUrl] = await Promise.all([
+                    signCompleteMultipartUpload(destinationConfig, finalObjectKey, uploadId, input.expiresIn),
+                    signAbortMultipartUpload(destinationConfig, finalObjectKey, uploadId, input.expiresIn),
+                    Promise.all(listPageMarkers.map((partNumberMarker) => signListMultipartUpload(destinationConfig, finalObjectKey, uploadId, input.expiresIn, { maxParts: 1_000, ...(partNumberMarker ? { partNumberMarker } : {}) }))),
+                    Promise.all(stagingListStartAfter.map((startAfter) => signListObjects(destinationConfig, stagingListPrefix, input.expiresIn, startAfter ? { startAfter } : {}))),
+                    signFinalObjectHead(destinationConfig, finalObjectKey, input.expiresIn)
+                ]);
+                const manifest = {
+                    multipart_group_id: multipartGroupId,
+                    source_id: source.source_id,
+                    destination_id: destination.destination_id,
+                    final_object_key: finalObjectKey,
+                    upload_id: uploadId,
+                    expected_object_size: source.size,
+                    expected_part_count: source.chunk_count,
+                    max_part_number: maxPartNumber,
+                    complete_url: completeUrl,
+                    abort_url: abortUrl,
+                    list_page_urls: listPageUrls,
+                    staging_list_urls: stagingListUrls,
+                    final_head_url: finalHeadUrl,
+                    final_object_metadata: finalObjectMetadata,
+                    urls_expires_at: urlsExpiresAt
+                };
+                const state = {
+                    destination: destinationConfig,
+                    objectKey: finalObjectKey,
+                    uploadId,
+                    manifest
+                };
+                input.multipartUploads.set(multipartGroupId, state);
+                return { ok: true, state };
+            }
+            catch (error) {
+                try {
+                    await abortMultipartUpload(destinationConfig, finalObjectKey, uploadId);
+                }
+                catch (abortError) {
+                    throw new AggregateError([error, abortError], `multipart group setup and cleanup failed for ${multipartGroupId}`);
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            return { ok: false, error };
+        }
+    });
+    const failure = results.find((result) => !result.ok);
+    if (failure && !failure.ok) {
+        try {
+            await abortCreatedUploads(input.multipartUploads);
+        }
+        catch (cleanupError) {
+            input.multipartUploads.clear();
+            throw new AggregateError([failure.error, cleanupError], "multipart manifest setup and cleanup failed");
+        }
+        input.multipartUploads.clear();
+        throw failure.error;
+    }
+    return results.flatMap((result) => result.ok && result.state ? [result.state.manifest] : []);
+}
+function multipartListPageMarkers(maxPartNumber) {
+    const markers = [];
+    for (let marker = 0; marker < maxPartNumber; marker += 1_000)
+        markers.push(marker);
+    return markers;
+}
+function multipartStagingObjectKeys(input) {
+    const encoder = new TextEncoder();
+    const keys = Array.from({ length: input.chunkCount }, (_, sourceChunkIndex) => {
+        const key = buildStagingObjectKey({
+            finalObjectKey: input.finalObjectKey,
+            transferId: input.transferId,
+            sourceId: input.sourceId,
+            destinationId: input.destinationId,
+            chunkIndex: input.globalChunkStart + sourceChunkIndex,
+            partNumber: multipartPartNumber(sourceChunkIndex)
+        });
+        return { key, bytes: encoder.encode(key) };
+    });
+    keys.sort((left, right) => compareBytes(left.bytes, right.bytes));
+    return keys.map(({ key }) => key);
+}
+function pagedListStartAfter(sortedKeys) {
+    const boundaries = [];
+    for (let pageStart = 0; pageStart < sortedKeys.length; pageStart += 1_000) {
+        boundaries.push(pageStart === 0 ? undefined : sortedKeys[pageStart - 1]);
+    }
+    return boundaries;
+}
+function compareBytes(leftBytes, rightBytes) {
+    const sharedLength = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        const difference = (leftBytes[index] ?? 0) - (rightBytes[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function multipartMaxPartNumber(chunkCount) {
+    return multipartPartNumber(positiveInteger(chunkCount, "source chunk_count") - 1);
+}
+function validateMultipartPartNumber(partNumber, manifest) {
+    if (!Number.isInteger(partNumber) || partNumber < 1 || partNumber > manifest.max_part_number) {
+        throw new Error(`multipart part_number ${partNumber} is outside group ${manifest.multipart_group_id} range 1-${manifest.max_part_number}`);
+    }
+}
+function validateSignedRouteManifestContract(routes, manifest) {
+    const groups = new Map(manifest.map((group) => [group.multipart_group_id, group]));
+    for (const route of routes) {
+        const groupId = typeof route.metadata?.multipart_group_id === "string"
+            ? route.metadata.multipart_group_id
+            : undefined;
+        if (!groupId)
+            continue;
+        const group = groups.get(groupId);
+        if (!group)
+            throw new Error(`signed route references unknown multipart group ${groupId}`);
+        if (route.source_id !== group.source_id || route.destination_id !== group.destination_id) {
+            throw new Error(`signed route identity does not match multipart group ${groupId}`);
+        }
+        const partNumber = route.metadata?.part_number;
+        if (typeof partNumber !== "number") {
+            throw new Error(`signed route for multipart group ${groupId} is missing part_number`);
+        }
+        validateMultipartPartNumber(partNumber, group);
+    }
+}
+const COMPACT_TRANSFER_PLAN_KEYS = new Set([
+    "version",
+    "plan_nonce",
+    "chunk_size",
+    "sources",
+    "destinations",
+    "logical_chunk_count",
+    "delivery_route_count",
+    "formulas"
+]);
+const COMPACT_TRANSFER_PLAN_FORMULAS = {
+    source_offset: "source_chunk_index * chunk_size",
+    delivery_index: "chunk_index * destination_count + destination_index",
+    part_number: "source_chunk_index + 1",
+    route_generation_id: "initial-{chunk_index}-{destination_id}",
+    staging_object_key: "{final_object_key}.beam-staging/{transfer_id}/{source_id}/{destination_id}/part-{part_number}-chunk-{chunk_index}"
+};
+function validateCompactTransferPlan(descriptor, signedUrlFlow) {
+    if (signedUrlFlow !== "signed_url_v2") {
+        throw new Error(`BeamCore returned unsupported signed_url_flow: ${String(signedUrlFlow)}`);
+    }
+    const keys = Object.keys(descriptor);
+    if (keys.length !== COMPACT_TRANSFER_PLAN_KEYS.size || keys.some((key) => !COMPACT_TRANSFER_PLAN_KEYS.has(key))) {
+        throw new Error("BeamCore returned invalid compact transfer plan fields");
+    }
+    if (descriptor.version !== "compact-transfer-plan/v1") {
+        throw new Error(`BeamCore returned unsupported plan version: ${descriptor.version}`);
+    }
+    const formulaKeys = Object.keys(descriptor.formulas);
+    if (formulaKeys.length !== Object.keys(COMPACT_TRANSFER_PLAN_FORMULAS).length
+        || Object.entries(COMPACT_TRANSFER_PLAN_FORMULAS).some(([key, value]) => descriptor.formulas[key] !== value)) {
+        throw new Error("BeamCore returned unsupported compact transfer plan formulas");
+    }
+}
+const MULTIPART_GROUP_MANIFEST_KEYS = new Set([
+    "multipart_group_id",
+    "source_id",
+    "destination_id",
+    "final_object_key",
+    "upload_id",
+    "expected_object_size",
+    "expected_part_count",
+    "max_part_number",
+    "complete_url",
+    "abort_url",
+    "list_page_urls",
+    "staging_list_urls",
+    "final_head_url",
+    "final_object_metadata",
+    "urls_expires_at"
+]);
+function validateMultipartGroupManifest(manifest, transferId) {
+    const groupIds = new Set();
+    for (const group of manifest) {
+        const keys = Object.keys(group);
+        if (keys.length !== MULTIPART_GROUP_MANIFEST_KEYS.size || keys.some((key) => !MULTIPART_GROUP_MANIFEST_KEYS.has(key))) {
+            throw new Error(`multipart group ${group.multipart_group_id || "<unknown>"} has invalid manifest fields`);
+        }
+        if (!group.multipart_group_id || groupIds.has(group.multipart_group_id)) {
+            throw new Error(`multipart_group_id must be non-empty and unique: ${group.multipart_group_id}`);
+        }
+        groupIds.add(group.multipart_group_id);
+        for (const [field, value] of Object.entries({
+            source_id: group.source_id,
+            destination_id: group.destination_id,
+            final_object_key: group.final_object_key,
+            upload_id: group.upload_id,
+            complete_url: group.complete_url,
+            abort_url: group.abort_url,
+            final_head_url: group.final_head_url,
+            urls_expires_at: group.urls_expires_at
+        })) {
+            if (typeof value !== "string" || value.length === 0) {
+                throw new Error(`multipart group ${group.multipart_group_id} requires ${field}`);
+            }
+        }
+        if (!Number.isInteger(group.expected_part_count) || group.expected_part_count < 1 || group.expected_part_count > 10_000) {
+            throw new Error(`multipart group ${group.multipart_group_id} has invalid expected_part_count`);
+        }
+        if (group.max_part_number !== group.expected_part_count) {
+            throw new Error(`multipart group ${group.multipart_group_id} max_part_number must equal expected_part_count`);
+        }
+        if (!Number.isSafeInteger(group.expected_object_size) || group.expected_object_size <= 0) {
+            throw new Error(`multipart group ${group.multipart_group_id} has invalid expected_object_size`);
+        }
+        const expectedListPageCount = Math.ceil(group.max_part_number / 1_000);
+        if (!Array.isArray(group.list_page_urls)
+            || group.list_page_urls.length !== expectedListPageCount
+            || new Set(group.list_page_urls).size !== expectedListPageCount
+            || group.list_page_urls.some((url) => typeof url !== "string" || url.length === 0)) {
+            throw new Error(`multipart group ${group.multipart_group_id} requires ${expectedListPageCount} unique list_page_urls`);
+        }
+        if (!Array.isArray(group.staging_list_urls)
+            || group.staging_list_urls.length !== expectedListPageCount
+            || new Set(group.staging_list_urls).size !== expectedListPageCount
+            || group.staging_list_urls.some((url) => typeof url !== "string" || url.length === 0)) {
+            throw new Error(`multipart group ${group.multipart_group_id} requires ${expectedListPageCount} unique staging_list_urls`);
+        }
+        const metadataKeys = Object.keys(group.final_object_metadata);
+        if (metadataKeys.length !== 2
+            || group.final_object_metadata["beam-transfer-id"] !== transferId
+            || group.final_object_metadata["beam-multipart-group-id"] !== group.multipart_group_id) {
+            throw new Error(`multipart group ${group.multipart_group_id} has invalid final_object_metadata`);
+        }
+    }
+}
+function multipartGroupStateKey(transferId, destinationId, sourceId, finalObjectKey) {
+    return `${transferId}:${destinationId}:${sourceId}:${finalObjectKey}`;
+}
+const PART_ROUTE_METADATA_KEYS = new Set([
+    "part_number",
+    "logical_attempt_index",
+    "attempt_slot",
+    "route_generation_id",
+    "delivery_index"
+]);
+function partRouteMetadata(metadata) {
+    return Object.fromEntries(Object.entries(metadata ?? {}).filter(([key]) => PART_ROUTE_METADATA_KEYS.has(key)));
+}
+function randomUuid() {
     const cryptoApi = globalThis.crypto;
     if (cryptoApi?.randomUUID)
         return cryptoApi.randomUUID();
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
+async function transferIdForIdempotencyKey(idempotencyKey) {
+    if (!idempotencyKey?.trim())
+        return randomUuid();
+    const input = new TextEncoder().encode(`beam-transfer:${idempotencyKey.trim()}`);
+    let digest;
+    if (globalThis.crypto?.subtle) {
+        digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", input));
+    }
+    else {
+        const { createHash } = await import("node:crypto");
+        digest = new Uint8Array(createHash("sha256").update(input).digest());
+    }
+    const bytes = digest.slice(0, 16);
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function jitteredDelay(baseMs) {
+    return Math.max(1, Math.round(baseMs * (0.8 + Math.random() * 0.4)));
+}
 function compact(input) {
     return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
 }
 export function buildStagingObjectPrefix(input) {
-    const base = input.finalObjectKey.replace(/\/+$/, "") || "object";
     return [
-        `${base}.beam-staging`,
-        safeObjectKeySegment(input.transferId),
-        safeObjectKeySegment(input.sourceId),
-        safeObjectKeySegment(input.destinationId)
+        `${input.finalObjectKey}.beam-staging`,
+        input.transferId,
+        input.sourceId,
+        input.destinationId
     ].join("/");
 }
 export function buildStagingObjectKey(input) {
@@ -690,21 +1085,26 @@ export function buildStagingObjectKey(input) {
         `part-${input.partNumber}-chunk-${input.chunkIndex}`
     ].join("/");
 }
-function safeObjectKeySegment(value) {
-    return encodeURIComponent(value).replace(/%2F/gi, "_");
-}
 function validateId(value, name) {
     if (!value || value.includes("/") || value.includes("..")) {
         throw new Error(`${name} is invalid`);
     }
 }
 async function abortCreatedUploads(uploads) {
-    await Promise.all([...uploads.values()].map(async (upload) => {
-        if (!upload.uploadId || isHippiusDestination(upload.destination)) {
-            return;
+    const candidates = [...uploads.values()].filter((upload) => upload.uploadId && !isHippiusDestination(upload.destination));
+    const results = await mapOrderedWithConcurrency(candidates, Math.min(32, Math.max(1, candidates.length)), async (upload) => {
+        try {
+            await abortMultipartUpload(upload.destination, upload.objectKey, upload.uploadId);
+            return null;
+        }
+        catch (error) {
+            return error;
         }
-        await abortMultipartUpload(upload.destination, upload.objectKey, upload.uploadId);
-    }));
+    });
+    const failures = results.filter((result) => result !== null);
+    if (failures.length) {
+        throw new AggregateError(failures, `failed to abort ${failures.length} multipart upload(s)`);
+    }
 }
 function isHippiusDestination(destination) {
     return destination.provider === "hippius" && "api_token" in destination;