@beam-network/sdk 0.4.4 → 0.5.1

package/README.md

@@ -96,10 +96,14 @@ For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport
 
 ## Route Streaming And Payload Size
 
-Provider transfers default to `signed_url_v1` and `transfer-client-control/v3`. S3, R2, and S3-compatible destinations create one final multipart upload per source/destination object, then each route signs direct `UploadPart` to that upload. Core receives per-route completion, abort, ListParts, and final HEAD controls and completes the destination after all winning ETags are known. `signed_url_v2` remains explicitly selectable for the legacy staged-copy manifest path.
+Provider transfers use `transfer-client-control/v5`. Every reply carries Runtime and transport epochs; prepare and every route-stream message carry a UUID route generation. S3, R2, and S3-compatible destinations retain direct multipart UploadPart/ListParts/HEAD handling.
 
 The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches, split only when encoded MessagePack requests exceed `maxPayloadBytes` (24 MiB by default). The stream ID derives from the transfer, selected flow, and immutable plan identity, and each ordered batch ID includes its route-coordinate checksum. Manual multi-destination attachment requires `delivery_index` on every route. Lifecycle mutations retry transient failures up to three times with the same request identity. `waitForTransfer` subscribes to the API-key-owned, at-most-once terminal signal before its first status read and reconciles every signal through authoritative status; subscription failure degrades to the same jittered 15-to-30-second status fallback. Call `close()` when the client is no longer needed; it also closes outstanding terminal waiters.
 
 Hippius uses genuine non-multipart v2 routes, so its manifest is empty and group-level final HEAD verification is not available from that provider flow.
 
 NATS requires this guard because the broker rejects messages above its configured `max_payload`. This limit applies only to lifecycle/control metadata; transfer file bytes do not flow through NATS.
+
+## Restart Recovery
+
+The client keeps one in-memory recovery lease per active transfer and one `runtime.hello` monitor per active shard. The lease is installed before route-stream begin, and a per-transfer lock coalesces initial streaming with replay. Multipart recovery retains the existing upload IDs and compact group state, then re-signs only the expiring route and commit controls. A Runtime epoch change invalidates cached auth, coalesces one `transfer.resume`, and regenerates routes under a fresh generation; a transport-only epoch change replays only when Runtime reports routes missing or expired. Provider credentials and signing inputs are retained only in memory and released on terminal status or `close()`. Low-level `attachSignedUrls` requires `routeGenerationId`, the plan fingerprint/checksum, and a `recoveryFactory`; signed URLs are never journaled to disk. Foreground cancellation, deadline expiry, and Runtime state-loss responses keep the background lease and retained multipart upload alive.

package/dist/client.d.ts

@@ -37,11 +37,20 @@ export declare class BeamClient {
         urlsExpiresAt?: string;
         signedUrlFlow?: SignedUrlFlow;
         idempotencyKey?: string;
+        routeGenerationId?: string;
     }): Promise<TransferPrepareResponse>;
     attachSignedUrls(transferId: string, input: {
         chunkRoutes: SignedChunkRoute[];
         multipartGroupManifest: MultipartGroupManifest[];
         transferKey?: string;
+        routeGenerationId: string;
+        planFingerprint: string;
+        coordinateChecksum: string;
+        recoveryFactory: (routeGenerationId: string) => Promise<{
+            chunkRoutes: SignedChunkRoute[];
+            multipartGroupManifest: MultipartGroupManifest[];
+            urlsExpiresAt?: string;
+        }>;
         urlsExpiresAt?: string;
         autoDistribute?: boolean;
     }): Promise<AttachSignedUrlsResponse>;

package/dist/client.js

@@ -1,5 +1,5 @@
 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 { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes, isRecoverableRouteStreamError } from "./nats-control.js";
 import { multipartPartNumber } from "./multipart-limits.js";
 export { BEAM_DEFAULT_NATS_URL };
 export class BeamApiError extends Error {
@@ -73,9 +73,12 @@ export class BeamClient {
     createTransfer(input) {
         return this.prepareProviderTransfer(input);
     }
-    transferStatus(transferId) {
+    async transferStatus(transferId) {
         validateId(transferId, "transferId");
-        return this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
+        const status = await this.control.request("transfer.status", { transfer_id: transferId }, { transferId });
+        if (["completed", "failed", "cancelled"].includes(status.status))
+            this.control.releaseRecoveryLease(transferId);
+        return status;
     }
     distributeTransfer(transferId) {
         validateId(transferId, "transferId");
@@ -90,6 +93,7 @@ export class BeamClient {
             transferId,
             idempotencyKey: `transfer:${transferId}:cancel`
         });
+        this.control.releaseRecoveryLease(transferId);
         return result;
     }
     async planTransfer(input) {
@@ -107,8 +111,10 @@ export class BeamClient {
     }
     async prepareTransfer(input) {
         const transferId = await transferIdForIdempotencyKey(input.idempotencyKey);
+        const routeGenerationId = input.routeGenerationId ?? randomUuid();
         const result = await this.control.request("transfer.prepare", compact({
             transfer_id: transferId,
+            route_generation_id: routeGenerationId,
             sources: input.sources,
             destinations: input.destinations,
             name: input.name,
@@ -127,56 +133,97 @@ export class BeamClient {
         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),
-            signedUrlFlow: input.multipartGroupManifest.length ? "signed_url_v2" : "signed_url_v1"
-        });
-        const stream = new RouteStreamSender(this.control, {
-            streamId,
+        const streamRoutes = async (chunkRoutes, multipartGroupManifest, routeGenerationId, urlsExpiresAt) => {
+            validateMultipartGroupManifest(multipartGroupManifest, transferId);
+            validateSignedRouteManifestContract(chunkRoutes, multipartGroupManifest);
+            const destinationCount = new Set(chunkRoutes.map((route) => route.destination_id)).size;
+            const orderedRoutes = 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)}:${routeGenerationId}`,
+                totalRoutes: orderedRoutes.length,
+                totalChunks: countDistinctRouteChunks(orderedRoutes),
+                signedUrlFlow: multipartGroupManifest.length ? "signed_url_v2" : "signed_url_v1"
+            });
+            const stream = new RouteStreamSender(this.control, {
+                streamId,
+                transferId,
+                routeGenerationId,
+                totalRoutes: orderedRoutes.length,
+                totalChunks: countDistinctRouteChunks(orderedRoutes),
+                urlsExpiresAt,
+                signedUrlFlow: multipartGroupManifest.length ? "signed_url_v2" : "signed_url_v1",
+                autoDistribute: input.autoDistribute ?? true
+            });
+            await stream.begin();
+            if (multipartGroupManifest.length)
+                await stream.addManifestGroups(multipartGroupManifest);
+            for (const route of orderedRoutes)
+                await stream.addRoute(route);
+            return stream.complete();
+        };
+        const routeStreamLock = new AsyncMutex();
+        const releaseInitialStream = await routeStreamLock.acquire();
+        this.control.registerRecoveryLease({
             transferId,
-            totalRoutes: orderedRoutes.length,
-            totalChunks: countDistinctRouteChunks(orderedRoutes),
-            urlsExpiresAt: input.urlsExpiresAt,
-            signedUrlFlow: input.multipartGroupManifest.length ? "signed_url_v2" : "signed_url_v1",
-            autoDistribute: input.autoDistribute ?? true
+            planFingerprint: input.planFingerprint,
+            coordinateChecksum: input.coordinateChecksum,
+            replayRoutes: async (routeGenerationId) => {
+                await routeStreamLock.run(async () => {
+                    const fresh = await input.recoveryFactory(routeGenerationId);
+                    const attached = await streamRoutes(fresh.chunkRoutes, fresh.multipartGroupManifest, routeGenerationId, fresh.urlsExpiresAt);
+                    if (!attached.success)
+                        throw new Error(attached.error ?? attached.message ?? "route replay failed");
+                });
+            }
         });
-        await stream.begin();
-        if (input.multipartGroupManifest.length) {
-            await stream.addManifestGroups(input.multipartGroupManifest);
+        try {
+            const attached = await streamRoutes(input.chunkRoutes, input.multipartGroupManifest, input.routeGenerationId, input.urlsExpiresAt);
+            if (!attached.success)
+                this.control.releaseRecoveryLease(transferId);
+            return attached;
         }
-        for (const route of orderedRoutes) {
-            await stream.addRoute(route);
+        catch (error) {
+            if (isRecoverableRouteStreamError(error))
+                this.control.continueRecoveryLease(transferId);
+            else
+                this.control.releaseRecoveryLease(transferId);
+            throw error;
+        }
+        finally {
+            releaseInitialStream();
         }
-        return stream.complete();
     }
     async prepareProviderTransfer(input) {
         const expiresIn = input.expiresIn ?? 3600;
         const requestedSignedUrlFlow = input.signedUrlFlow ?? "signed_url_v1";
-        const preparedDestinations = input.destinations.map((destination, index) => prepareProviderDestination(destination, { index }));
+        const retainedRecoveryInput = {
+            ...input,
+            sources: input.sources.map((source) => ({ ...source })),
+            destinations: input.destinations.map((destination) => ({ ...destination })),
+            onBeforeTransferPrepare: undefined,
+            onPrepared: undefined,
+            throwIfCancelled: undefined
+        };
+        const preparedDestinations = retainedRecoveryInput.destinations.map((destination, index) => prepareProviderDestination(destination, { index }));
         const destinationsById = new Map();
         preparedDestinations.forEach((preparedDestination, index) => {
-            const destination = input.destinations[index];
+            const destination = retainedRecoveryInput.destinations[index];
             if (!destination) {
                 throw new Error(`missing provider destination config for prepared destination ${preparedDestination.destination_id}`);
             }
             destinationsById.set(preparedDestination.destination_id, destination);
         });
         await input.throwIfCancelled?.();
-        const preparedSources = await Promise.all(input.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
+        const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl })));
         await input.throwIfCancelled?.();
         await input.onBeforeTransferPrepare?.();
         const prepared = await this.prepareTransfer({
@@ -185,145 +232,201 @@ export class BeamClient {
             name: input.name,
             testMode: input.testMode,
             signedUrlFlow: requestedSignedUrlFlow,
-            idempotencyKey: input.idempotencyKey
+            idempotencyKey: input.idempotencyKey,
+            routeGenerationId: input.routeGenerationId
         });
         if (!prepared.success) {
             return prepared;
         }
-        await input.onPrepared?.(prepared);
-        await input.throwIfCancelled?.(prepared.transfer_id);
         const sourcesById = new Map();
         preparedSources.forEach((preparedSource, index) => {
-            const source = input.sources[index];
+            const source = retainedRecoveryInput.sources[index];
             if (!source) {
                 throw new Error(`missing provider source config for prepared source ${preparedSource.source_id}`);
             }
             sourcesById.set(preparedSource.source_id, source);
         });
         const multipartUploads = new Map();
-        const pendingRoutes = new Set();
-        let signingConcurrency = this.routeSigningConcurrency;
-        let signedInWindow = 0;
-        let signingWindowStartedAt = performance.now();
-        let routeStream = null;
-        let routeStreamBeginAttempted = false;
-        let multipartManifestTask = null;
-        let multipartGroupWaiters = new Map();
-        try {
-            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,
-                signedUrlFlow: requestedSignedUrlFlow
-            });
-            routeStream = new RouteStreamSender(this.control, {
-                streamId,
-                transferId: prepared.transfer_id,
-                totalRoutes: prepared.plan_descriptor.delivery_route_count,
-                totalChunks: prepared.plan_descriptor.logical_chunk_count,
-                signedUrlFlow: requestedSignedUrlFlow,
-                autoDistribute: input.distribute !== false
-            });
-            routeStreamBeginAttempted = true;
-            await routeStream.begin();
-            multipartGroupWaiters = createMultipartGroupWaiters(prepared, destinationsById);
-            multipartManifestTask = createMultipartGroupManifest({
-                prepared,
-                destinationsById,
-                multipartUploads,
-                expiresIn,
-                signedUrlFlow: requestedSignedUrlFlow,
-                concurrency: this.routeSigningConcurrency,
-                onGroupReady: async (state) => {
-                    if (requestedSignedUrlFlow === "signed_url_v2") {
-                        validateMultipartGroupManifest([state.manifest], prepared.transfer_id);
-                        await routeStream.addManifestGroups([state.manifest]);
+        const autoDistribute = input.distribute !== false;
+        let initialThrowIfCancelled = input.throwIfCancelled;
+        const routeStreamLock = new AsyncMutex();
+        const releaseInitialStream = await routeStreamLock.acquire();
+        const streamPreparedRoutes = async (routeGenerationId, recoveryReplay) => {
+            const pendingRoutes = new Set();
+            let signingConcurrency = this.routeSigningConcurrency;
+            let signedInWindow = 0;
+            let signingWindowStartedAt = performance.now();
+            let routeStream = null;
+            let routeStreamBeginAttempted = false;
+            let multipartManifestTask = null;
+            let multipartGroupWaiters = new Map();
+            let foregroundCancelled = false;
+            const throwIfCancelled = recoveryReplay || !initialThrowIfCancelled ? undefined : async (transferId) => {
+                try {
+                    await initialThrowIfCancelled?.(transferId);
+                }
+                catch (error) {
+                    foregroundCancelled = true;
+                    throw error;
+                }
+            };
+            try {
+                const streamId = await stableRouteStreamId({
+                    transferId: prepared.transfer_id,
+                    planIdentity: `${prepared.plan_descriptor.plan_nonce}:${routeGenerationId}`,
+                    totalRoutes: prepared.plan_descriptor.delivery_route_count,
+                    totalChunks: prepared.plan_descriptor.logical_chunk_count,
+                    signedUrlFlow: requestedSignedUrlFlow
+                });
+                routeStream = new RouteStreamSender(this.control, {
+                    streamId,
+                    transferId: prepared.transfer_id,
+                    routeGenerationId,
+                    totalRoutes: prepared.plan_descriptor.delivery_route_count,
+                    totalChunks: prepared.plan_descriptor.logical_chunk_count,
+                    signedUrlFlow: requestedSignedUrlFlow,
+                    autoDistribute,
+                    urlsExpiresAt: expiresAtIso(expiresIn)
+                });
+                routeStreamBeginAttempted = true;
+                await routeStream.begin();
+                multipartGroupWaiters = createMultipartGroupWaiters(prepared, destinationsById);
+                multipartManifestTask = createMultipartGroupManifest({
+                    prepared,
+                    destinationsById,
+                    multipartUploads,
+                    expiresIn,
+                    signedUrlFlow: requestedSignedUrlFlow,
+                    concurrency: this.routeSigningConcurrency,
+                    preserveUploadsOnFailure: recoveryReplay,
+                    onGroupReady: async (state) => {
+                        if (requestedSignedUrlFlow === "signed_url_v2") {
+                            validateMultipartGroupManifest([state.manifest], prepared.transfer_id);
+                            await routeStream.addManifestGroups([state.manifest]);
+                        }
+                        multipartGroupWaiters.get(state.manifest.multipart_group_id)?.resolve(state);
+                    },
+                    onGroupFailed: (groupId, error) => multipartGroupWaiters.get(groupId)?.reject(error)
+                });
+                const streamNextCompletedRoute = async () => {
+                    const settled = await Promise.race([...pendingRoutes].map((pending) => pending.then((route) => ({ pending, route }))));
+                    pendingRoutes.delete(settled.pending);
+                    await routeStream.addRoute(settled.route);
+                    signedInWindow += 1;
+                    if (signedInWindow === ROUTE_STREAM_BATCH_ROUTES) {
+                        const elapsedMs = performance.now() - signingWindowStartedAt;
+                        if (!this.routeSigningConcurrencyOverridden && elapsedMs > 4_000 && signingConcurrency < 256) {
+                            signingConcurrency = Math.min(256, signingConcurrency * 2);
+                        }
+                        signedInWindow = 0;
+                        signingWindowStartedAt = performance.now();
                     }
-                    multipartGroupWaiters.get(state.manifest.multipart_group_id)?.resolve(state);
-                },
-                onGroupFailed: (groupId, error) => multipartGroupWaiters.get(groupId)?.reject(error)
-            });
-            const streamNextCompletedRoute = async () => {
-                const settled = await Promise.race([...pendingRoutes].map((pending) => pending.then((route) => ({ pending, route }))));
-                pendingRoutes.delete(settled.pending);
-                await routeStream.addRoute(settled.route);
-                signedInWindow += 1;
-                if (signedInWindow === ROUTE_STREAM_BATCH_ROUTES) {
-                    const elapsedMs = performance.now() - signingWindowStartedAt;
-                    if (!this.routeSigningConcurrencyOverridden && elapsedMs > 4_000 && signingConcurrency < 256) {
-                        signingConcurrency = Math.min(256, signingConcurrency * 2);
+                };
+                for (const chunk of materializePlanChunks(prepared.plan_descriptor, prepared.transfer_id)) {
+                    await throwIfCancelled?.(prepared.transfer_id);
+                    for (const target of chunk.destinations) {
+                        const pendingRoute = (async () => {
+                            await throwIfCancelled?.(prepared.transfer_id);
+                            const destination = destinationsById.get(target.destination_id);
+                            if (!destination)
+                                throw new Error(`BeamCore returned unknown destination_id: ${target.destination_id}`);
+                            const source = sourcesById.get(chunk.source_id);
+                            if (!source)
+                                throw new Error(`BeamCore returned unknown source_id: ${chunk.source_id}`);
+                            const metadata = target.metadata ?? {};
+                            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 multipartGroupId = multipartGroupStateKey(prepared.transfer_id, target.destination_id, chunk.source_id, finalObjectKey);
+                            const upload = isHippiusDestination(destination)
+                                ? undefined
+                                : await multipartGroupWaiters.get(multipartGroupId)?.promise;
+                            if (!isHippiusDestination(destination) && !upload)
+                                throw new Error(`multipart group manifest is missing for ${chunk.source_id}:${target.destination_id}`);
+                            return this.signProviderRoute({
+                                chunk,
+                                target,
+                                source,
+                                destination,
+                                expiresIn,
+                                ...(upload ? { upload } : {}),
+                                transferId: prepared.transfer_id,
+                                finalObjectKey,
+                                signedUrlFlow: requestedSignedUrlFlow,
+                                partNumber: typeof metadata.part_number === "number"
+                                    ? metadata.part_number
+                                    : multipartPartNumber(chunk.source_chunk_index),
+                            });
+                        })();
+                        pendingRoutes.add(pendingRoute);
+                        if (pendingRoutes.size >= signingConcurrency)
+                            await streamNextCompletedRoute();
                     }
-                    signedInWindow = 0;
-                    signingWindowStartedAt = performance.now();
                 }
-            };
-            for (const chunk of materializePlanChunks(prepared.plan_descriptor, prepared.transfer_id)) {
-                await input.throwIfCancelled?.(prepared.transfer_id);
-                for (const target of chunk.destinations) {
-                    const pendingRoute = (async () => {
-                        await input.throwIfCancelled?.(prepared.transfer_id);
-                        const destination = destinationsById.get(target.destination_id);
-                        if (!destination)
-                            throw new Error(`BeamCore returned unknown destination_id: ${target.destination_id}`);
-                        const source = sourcesById.get(chunk.source_id);
-                        if (!source)
-                            throw new Error(`BeamCore returned unknown source_id: ${chunk.source_id}`);
-                        const metadata = target.metadata ?? {};
-                        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 multipartGroupId = multipartGroupStateKey(prepared.transfer_id, target.destination_id, chunk.source_id, finalObjectKey);
-                        const upload = isHippiusDestination(destination)
-                            ? undefined
-                            : await multipartGroupWaiters.get(multipartGroupId)?.promise;
-                        if (!isHippiusDestination(destination) && !upload)
-                            throw new Error(`multipart group manifest is missing for ${chunk.source_id}:${target.destination_id}`);
-                        return this.signProviderRoute({
-                            chunk,
-                            target,
-                            source,
-                            destination,
-                            expiresIn,
-                            ...(upload ? { upload } : {}),
+                while (pendingRoutes.size)
+                    await streamNextCompletedRoute();
+                const multipartGroupManifest = await multipartManifestTask;
+                if (requestedSignedUrlFlow === "signed_url_v2") {
+                    validateMultipartGroupManifest(multipartGroupManifest, prepared.transfer_id);
+                }
+                const attached = await routeStream.complete();
+                if (!attached.success) {
+                    throw new Error(attached.error ?? attached.message ?? "route stream failed");
+                }
+            }
+            catch (error) {
+                if (routeStream)
+                    await routeStream.abort().catch(() => undefined);
+                await Promise.allSettled(pendingRoutes);
+                if (multipartManifestTask)
+                    await Promise.allSettled([multipartManifestTask]);
+                if (!recoveryReplay) {
+                    if (foregroundCancelled || isRecoverableRouteStreamError(error)) {
+                        this.control.continueRecoveryLease(prepared.transfer_id);
+                    }
+                    else {
+                        this.control.releaseRecoveryLease(prepared.transfer_id);
+                        await cancelAndAbortProviderFailure({
+                            client: this,
                             transferId: prepared.transfer_id,
-                            finalObjectKey,
-                            signedUrlFlow: requestedSignedUrlFlow,
-                            partNumber: typeof metadata.part_number === "number"
-                                ? metadata.part_number
-                                : multipartPartNumber(chunk.source_chunk_index),
+                            cause: error,
+                            uploads: multipartUploads,
+                            abortBeforeCancel: !routeStreamBeginAttempted
                         });
-                    })();
-                    pendingRoutes.add(pendingRoute);
-                    if (pendingRoutes.size >= signingConcurrency)
-                        await streamNextCompletedRoute();
+                    }
                 }
+                throw error;
             }
-            while (pendingRoutes.size)
-                await streamNextCompletedRoute();
-            const multipartGroupManifest = await multipartManifestTask;
-            if (requestedSignedUrlFlow === "signed_url_v2") {
-                validateMultipartGroupManifest(multipartGroupManifest, prepared.transfer_id);
+        };
+        this.control.registerRecoveryLease({
+            transferId: prepared.transfer_id,
+            planFingerprint: prepared.plan_fingerprint,
+            coordinateChecksum: prepared.coordinate_checksum,
+            replayRoutes: async (routeGenerationId) => {
+                await routeStreamLock.run(() => streamPreparedRoutes(routeGenerationId, true));
+            },
+            disposeSecrets: () => clearRecoverySecrets(retainedRecoveryInput)
+        });
+        try {
+            try {
+                await input.onPrepared?.(prepared);
             }
-            const attached = await routeStream.complete();
-            if (!attached.success) {
-                throw new Error(attached.error ?? attached.message ?? "route stream failed");
+            catch (error) {
+                this.control.continueRecoveryLease(prepared.transfer_id);
+                throw error;
             }
+            try {
+                await input.throwIfCancelled?.(prepared.transfer_id);
+            }
+            catch (error) {
+                this.control.continueRecoveryLease(prepared.transfer_id);
+                throw error;
+            }
+            await streamPreparedRoutes(prepared.route_generation_id, false);
+            initialThrowIfCancelled = undefined;
         }
-        catch (error) {
-            if (routeStream)
-                await routeStream.abort();
-            await Promise.allSettled(pendingRoutes);
-            if (multipartManifestTask)
-                await Promise.allSettled([multipartManifestTask]);
-            await cancelAndAbortProviderFailure({
-                client: this,
-                transferId: prepared.transfer_id,
-                cause: error,
-                uploads: multipartUploads,
-                abortBeforeCancel: !routeStreamBeginAttempted
-            });
-            throw error;
+        finally {
+            releaseInitialStream();
         }
         return prepared;
     }
@@ -488,6 +591,27 @@ export class BeamClient {
     }
 }
 const ROUTE_STREAM_BATCH_ROUTES = 2_048;
+class AsyncMutex {
+    tail = Promise.resolve();
+    async acquire() {
+        const previous = this.tail;
+        let release;
+        this.tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        return release;
+    }
+    async run(operation) {
+        const release = await this.acquire();
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+}
 class RouteStreamSender {
     control;
     options;
@@ -507,6 +631,7 @@ class RouteStreamSender {
     async begin() {
         await this.control.request("transfer.route_stream.begin", compact({
             transfer_id: this.options.transferId,
+            route_generation_id: this.options.routeGenerationId,
             stream_id: this.streamId,
             total_routes: this.options.totalRoutes,
             total_chunks: this.options.totalChunks,
@@ -526,6 +651,7 @@ class RouteStreamSender {
             const identity = await stableManifestBatchIdentity([group]);
             await this.control.request("transfer.route_stream.manifest", {
                 transfer_id: this.options.transferId,
+                route_generation_id: this.options.routeGenerationId,
                 stream_id: this.streamId,
                 manifest_batch_id: identity,
                 groups: [group]
@@ -564,6 +690,7 @@ class RouteStreamSender {
             throw this.sendError;
         return this.control.request("transfer.route_stream.complete", {
             transfer_id: this.options.transferId,
+            route_generation_id: this.options.routeGenerationId,
             stream_id: this.streamId,
             expected_batches: this.batchIndex,
             expected_routes: this.options.totalRoutes,
@@ -582,6 +709,7 @@ class RouteStreamSender {
         const routes = this.batch.splice(0, this.batch.length);
         const chunks = this.control.splitRoutesForPayload("transfer.route_stream.batch", {
             transfer_id: this.options.transferId,
+            route_generation_id: this.options.routeGenerationId,
             stream_id: this.streamId,
             batch_id: `${this.streamId}:estimate`,
             batch_index: this.batchIndex
@@ -601,6 +729,7 @@ class RouteStreamSender {
                     const batchId = `${this.streamId}:${batchIndex}:${coordinateChecksum}`;
                     await this.control.request("transfer.route_stream.batch", {
                         transfer_id: this.options.transferId,
+                        route_generation_id: this.options.routeGenerationId,
                         stream_id: this.streamId,
                         batch_id: batchId,
                         batch_index: batchIndex,
@@ -880,11 +1009,13 @@ async function createMultipartGroupManifest(input) {
                 "beam-transfer-id": input.prepared.transfer_id,
                 ...(input.signedUrlFlow === "signed_url_v2" ? { "beam-multipart-group-id": multipartGroupId } : {})
             };
-            const uploadId = await createMultipartUpload({
+            const retainedUpload = input.multipartUploads.get(multipartGroupId);
+            const uploadId = retainedUpload?.uploadId ?? await createMultipartUpload({
                 destination: destinationConfig,
                 objectKey: finalObjectKey,
                 metadata: finalObjectMetadata
             });
+            const createdUpload = !retainedUpload;
             try {
                 const urlsExpiresAt = expiresAtIso(input.expiresIn);
                 const stagingObjectPrefix = buildStagingObjectPrefix({
@@ -942,11 +1073,13 @@ async function createMultipartGroupManifest(input) {
                 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}`);
+                if (createdUpload) {
+                    try {
+                        await abortMultipartUpload(destinationConfig, finalObjectKey, uploadId);
+                    }
+                    catch (abortError) {
+                        throw new AggregateError([error, abortError], `multipart group setup and cleanup failed for ${multipartGroupId}`);
+                    }
                 }
                 throw error;
             }
@@ -959,6 +1092,8 @@ async function createMultipartGroupManifest(input) {
     });
     const failure = results.find((result) => !result.ok);
     if (failure && !failure.ok) {
+        if (input.preserveUploadsOnFailure)
+            throw failure.error;
         try {
             await abortCreatedUploads(input.multipartUploads);
         }
@@ -1237,3 +1372,13 @@ function isHippiusDestination(destination) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function clearRecoverySecrets(input) {
+    const secretKeys = new Set(["access_key_id", "secret_access_key", "session_token", "api_token", "token", "password"]);
+    for (const provider of [...input.sources, ...input.destinations]) {
+        const record = provider;
+        for (const key of secretKeys) {
+            if (key in record)
+                record[key] = "";
+        }
+    }
+}

package/dist/models.d.ts

@@ -70,6 +70,8 @@ export interface RawTransferCreateInput {
     progressiveMode?: boolean;
     signedUrlFlow?: SignedUrlFlow;
     idempotencyKey?: string;
+    /** Internal recovery generation; callers normally leave this unset. */
+    routeGenerationId?: string;
 }
 export interface TransferCreateResponse {
     success: boolean;
@@ -145,7 +147,7 @@ export interface TransferStatusInfo {
     };
 }
 export interface TransferTerminalEvent {
-    schema_version: "transfer-client-control/v4";
+    schema_version: "transfer-client-control/v5";
     producer: "transfer-runtime";
     transfer_id: string;
     status: "completed" | "failed" | "cancelled";
@@ -176,23 +178,6 @@ export interface R2ProviderConfig {
     account_id?: string;
     endpoint_url?: string;
 }
-export interface S3CompatibleProviderCapabilities {
-    /**
-     * Whether the provider's ListParts / ListObjects response includes a per-part
-     * LastModified timestamp. Defaults to true (S3-spec compliant). Providers that
-     * omit it (e.g. Hippius) declare false so Beam finalization substitutes a
-     * Beam-side timestamp instead of looping into multipart recovery.
-     */
-    multipart_part_last_modified?: boolean;
-    /**
-     * Per-destination override for Beam Core's assignment-recovery deadline
-     * (TRANSFER_ASSIGNMENT_TIMEOUT_MS), in milliseconds. Omit to use the global
-     * default (15s). Slower providers (e.g. Hippius) declare a larger value so
-     * their assignment waves aren't reassigned prematurely. Only integers >= 1000
-     * are honoured by Beam Core.
-     */
-    assignment_timeout_ms?: number;
-}
 export interface S3CompatibleProviderConfig {
     provider: string;
     driver?: "s3-compatible";
@@ -206,7 +191,6 @@ export interface S3CompatibleProviderConfig {
     session_token?: string;
     force_path_style?: boolean;
     account_id?: string;
-    capabilities?: S3CompatibleProviderCapabilities;
 }
 export interface HippiusProviderConfig {
     provider: "hippius";
@@ -254,6 +238,8 @@ export interface ProviderTransferCreateInput {
     signedUrlFlow?: SignedUrlFlow;
     /** Stable caller identity used to derive the transfer and lifecycle request ids. */
     idempotencyKey?: string;
+    /** Internal recovery generation; callers normally omit this. */
+    routeGenerationId?: string;
 }
 export interface PlanningHttpSource {
     source_id: string;
@@ -359,6 +345,8 @@ export interface TransferPlanResponse {
     total_chunks?: number;
     plan_descriptor: CompactTransferPlanDescriptor;
     signed_url_flow: SignedUrlFlow;
+    plan_fingerprint: string;
+    coordinate_checksum: string;
     error?: string;
     message?: string;
 }
@@ -375,6 +363,9 @@ export interface TransferPrepareResponse {
     total_chunks?: number;
     plan_descriptor: CompactTransferPlanDescriptor;
     signed_url_flow: SignedUrlFlow;
+    plan_fingerprint: string;
+    coordinate_checksum: string;
+    route_generation_id: string;
     error?: string;
     message?: string;
 }

package/dist/nats-control.d.ts

@@ -1,9 +1,10 @@
+import { type ConnectionOptions } from "nats";
 import type { MultipartGroupManifest, SignedChunkRoute, TransferTerminalSignalWaiter } from "./models.js";
-export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v4";
+export declare const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v5";
 export declare const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
 export declare const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
 export declare const BEAM_DEFAULT_MAX_PAYLOAD_BYTES: number;
-export type TransferClientMessageType = "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.route_stream.begin" | "transfer.route_stream.manifest" | "transfer.route_stream.batch" | "transfer.route_stream.complete" | "transfer.distribute" | "transfer.status" | "transfer.cancel";
+export type TransferClientMessageType = "runtime.hello" | "transfer.plan" | "transfer.create" | "transfer.prepare" | "transfer.route_stream.begin" | "transfer.route_stream.manifest" | "transfer.route_stream.batch" | "transfer.route_stream.complete" | "transfer.distribute" | "transfer.status" | "transfer.cancel" | "transfer.resume";
 export interface CompactSignedRouteBatch {
     source_chunks: Array<{
         source_ref: number;
@@ -28,6 +29,7 @@ export interface CompactSignedRouteBatch {
 }
 export interface RouteStreamBeginPayload {
     transfer_id: string;
+    route_generation_id: string;
     stream_id: string;
     total_routes: number;
     total_chunks: number;
@@ -38,10 +40,16 @@ export interface RouteStreamBeginPayload {
 }
 export interface RouteStreamManifestPayload {
     transfer_id: string;
+    route_generation_id: string;
     stream_id: string;
     manifest_batch_id: string;
     groups: MultipartGroupManifest[];
 }
+export declare function buildConnectionOptions(options: {
+    natsUrl: string;
+    apiKey: string;
+    keyPrefix: string;
+}): ConnectionOptions;
 export interface TransferControlOptions {
     apiKey: string;
     natsUrl?: string;
@@ -55,6 +63,14 @@ export interface TransferControlOptions {
 export interface LifecycleRequestOptions {
     transferId?: string;
     idempotencyKey?: string;
+    shardId?: number;
+}
+export interface TransferRecoveryLease {
+    transferId: string;
+    planFingerprint: string;
+    coordinateChecksum: string;
+    replayRoutes(routeGenerationId: string): Promise<void>;
+    disposeSecrets?(): void;
 }
 export declare class BeamTransferControl {
     readonly environment: string;
@@ -72,12 +88,24 @@ export declare class BeamTransferControl {
     private authTokenExpiresAt;
     private authResolvePromise;
     private readonly terminalWaitCancellations;
+    private readonly recoveryLeases;
+    private readonly recoveryOperations;
+    private readonly recoveryRequestedEpoch;
+    private readonly runtimeEpochs;
+    private helloTimer;
     constructor(options: TransferControlOptions);
     close(): Promise<void>;
+    registerRecoveryLease(lease: TransferRecoveryLease): () => void;
+    releaseRecoveryLease(transferId: string): void;
+    continueRecoveryLease(transferId: string): void;
     request<T>(messageType: TransferClientMessageType, payload: Record<string, unknown>, options?: LifecycleRequestOptions): Promise<T>;
     openTerminalSignalWaiter(transferId: string): Promise<TransferTerminalSignalWaiter>;
     splitRoutesForPayload(messageType: TransferClientMessageType, basePayload: Record<string, unknown>, routes: SignedChunkRoute[]): SignedChunkRoute[][];
     private connection;
+    private ensureHelloMonitor;
+    private pollRuntimeHello;
+    private observeRuntimeEpoch;
+    private recoverLease;
     private resolveAuthToken;
     private resolveAuthTokenFresh;
     private authSubject;
@@ -86,3 +114,5 @@ export declare class BeamTransferControl {
 }
 export declare function compactSignedRoutes(routes: SignedChunkRoute[]): CompactSignedRouteBatch;
 export declare function transferShardId(transferId: string, shardCount: number): number;
+export declare function isRetryableLifecycleError(error: unknown): boolean;
+export declare function isRecoverableRouteStreamError(error: unknown): boolean;

package/dist/nats-control.js

@@ -1,17 +1,22 @@
 import { encode, decode } from "@msgpack/msgpack";
 import { connect } from "nats";
-export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v4";
+export const TRANSFER_CLIENT_CONTROL_SCHEMA_VERSION = "transfer-client-control/v5";
 export const BEAM_DEFAULT_NATS_URL = "tls://nats.b1m.ai:4222";
 export const BEAM_DEFAULT_NATS_WS_URL = "wss://nats.b1m.ai:443";
 // NATS enforces max_payload per message. This guard splits signed-route control
 // messages before the broker rejects them; transfer bytes never flow through NATS.
 export const BEAM_DEFAULT_MAX_PAYLOAD_BYTES = 24 * 1024 * 1024;
-function buildConnectionOptions(options) {
+export function buildConnectionOptions(options) {
     const connectionOptions = {
         servers: options.natsUrl,
         user: options.keyPrefix,
         pass: options.apiKey,
-        name: `beam-sdk-${options.keyPrefix}`
+        name: `beam-sdk-${options.keyPrefix}`,
+        reconnect: true,
+        maxReconnectAttempts: -1,
+        reconnectTimeWait: 1_000,
+        reconnectJitter: 500,
+        reconnectJitterTLS: 1_000
     };
     if (options.natsUrl.startsWith("tls://")) {
         const tlsOptions = { handshakeFirst: true };
@@ -25,6 +30,14 @@ function buildConnectionOptions(options) {
     }
     return connectionOptions;
 }
+class LifecycleRequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "LifecycleRequestError";
+    }
+}
 export class BeamTransferControl {
     environment;
     keyPrefix;
@@ -41,6 +54,11 @@ export class BeamTransferControl {
     authTokenExpiresAt = 0;
     authResolvePromise = null;
     terminalWaitCancellations = new Set();
+    recoveryLeases = new Map();
+    recoveryOperations = new Map();
+    recoveryRequestedEpoch = new Map();
+    runtimeEpochs = new Map();
+    helloTimer = null;
     constructor(options) {
         this.apiKey = options.apiKey;
         this.keyPrefix = options.apiKey.slice(0, 12);
@@ -61,6 +79,13 @@ export class BeamTransferControl {
         this.closed = true;
         for (const cancel of [...this.terminalWaitCancellations])
             cancel();
+        if (this.helloTimer)
+            clearInterval(this.helloTimer);
+        this.helloTimer = null;
+        for (const lease of this.recoveryLeases.values())
+            lease.disposeSecrets?.();
+        this.recoveryLeases.clear();
+        this.recoveryRequestedEpoch.clear();
         if (this.connectionPromise) {
             try {
                 await this.connectionPromise;
@@ -74,9 +99,53 @@ export class BeamTransferControl {
         if (nc && !nc.isClosed())
             await nc.drain();
     }
+    registerRecoveryLease(lease) {
+        if (this.closed)
+            throw new Error("NATS lifecycle control is closed");
+        const previous = this.recoveryLeases.get(lease.transferId);
+        if (previous && previous !== lease)
+            previous.disposeSecrets?.();
+        this.recoveryLeases.set(lease.transferId, lease);
+        this.ensureHelloMonitor();
+        const shardId = transferShardId(lease.transferId, this.shardCount);
+        void this.pollRuntimeHello(shardId);
+        return () => {
+            const current = this.recoveryLeases.get(lease.transferId);
+            if (current !== lease)
+                return;
+            this.recoveryLeases.delete(lease.transferId);
+            this.recoveryRequestedEpoch.delete(lease.transferId);
+            lease.disposeSecrets?.();
+            if (!this.recoveryLeases.size && this.helloTimer) {
+                clearInterval(this.helloTimer);
+                this.helloTimer = null;
+            }
+        };
+    }
+    releaseRecoveryLease(transferId) {
+        const lease = this.recoveryLeases.get(transferId);
+        if (!lease)
+            return;
+        this.recoveryLeases.delete(transferId);
+        this.recoveryRequestedEpoch.delete(transferId);
+        lease.disposeSecrets?.();
+        if (!this.recoveryLeases.size && this.helloTimer) {
+            clearInterval(this.helloTimer);
+            this.helloTimer = null;
+        }
+    }
+    continueRecoveryLease(transferId) {
+        const lease = this.recoveryLeases.get(transferId);
+        if (!lease || this.closed)
+            return;
+        const shardId = transferShardId(transferId, this.shardCount);
+        const epoch = this.runtimeEpochs.get(shardId);
+        this.recoveryRequestedEpoch.set(transferId, epoch ? `${epoch.runtimeEpoch}:${epoch.transportEpoch}` : `foreground:${randomId()}`);
+        void this.recoverLease(lease);
+    }
     async request(messageType, payload, options = {}) {
         const authToken = await this.resolveAuthToken();
-        const shardId = options.transferId ? transferShardId(options.transferId, this.shardCount) : 0;
+        const shardId = options.shardId ?? (options.transferId ? transferShardId(options.transferId, this.shardCount) : 0);
         const requestId = options.idempotencyKey
             ? await stableRequestId(`${messageType}:${options.idempotencyKey}`)
             : randomId();
@@ -104,10 +173,11 @@ export class BeamTransferControl {
                 const nc = await this.connection();
                 const response = await nc.request(subject, bytes, { timeout: this.requestTimeoutMs });
                 const decoded = decode(response.data);
+                this.observeRuntimeEpoch(shardId, decoded.runtime_epoch, decoded.transport_epoch);
                 if (decoded.ok)
                     return (decoded.payload ?? {});
                 const body = JSON.stringify(decoded.error ?? {});
-                const error = new Error(`Beam lifecycle request failed with ${decoded.status}: ${body}`);
+                const error = new LifecycleRequestError(decoded.status, `Beam lifecycle request failed with ${decoded.status}: ${body}`);
                 if (!isRetryableLifecycleStatus(decoded.status) || attempt + 1 >= LIFECYCLE_REQUEST_MAX_ATTEMPTS) {
                     throw error;
                 }
@@ -282,6 +352,96 @@ export class BeamTransferControl {
                 this.connectionPromise = null;
         }
     }
+    ensureHelloMonitor() {
+        if (this.helloTimer || this.closed)
+            return;
+        this.helloTimer = setInterval(() => {
+            const shards = new Set([...this.recoveryLeases.keys()].map((transferId) => transferShardId(transferId, this.shardCount)));
+            for (const shardId of shards)
+                void this.pollRuntimeHello(shardId);
+        }, 5_000);
+        this.helloTimer.unref?.();
+    }
+    async pollRuntimeHello(shardId) {
+        try {
+            await this.request("runtime.hello", {}, { idempotencyKey: `runtime:hello:${shardId}`, shardId });
+        }
+        catch {
+            // Infinite NATS reconnect continues in the background; the next hello reconciles epochs.
+        }
+    }
+    observeRuntimeEpoch(shardId, runtimeEpoch, transportEpoch) {
+        if (!runtimeEpoch || !transportEpoch)
+            return;
+        const previous = this.runtimeEpochs.get(shardId);
+        this.runtimeEpochs.set(shardId, { runtimeEpoch, transportEpoch });
+        if (!previous)
+            return;
+        if (previous.runtimeEpoch === runtimeEpoch && previous.transportEpoch === transportEpoch)
+            return;
+        if (previous.runtimeEpoch !== runtimeEpoch) {
+            this.authToken = null;
+            this.authTokenExpiresAt = 0;
+        }
+        for (const lease of this.recoveryLeases.values()) {
+            if (transferShardId(lease.transferId, this.shardCount) === shardId) {
+                this.recoveryRequestedEpoch.set(lease.transferId, `${runtimeEpoch}:${transportEpoch}`);
+                void this.recoverLease(lease);
+            }
+        }
+    }
+    recoverLease(lease) {
+        const existing = this.recoveryOperations.get(lease.transferId);
+        if (existing)
+            return existing;
+        let operation;
+        operation = (async () => {
+            let attempt = 0;
+            while (!this.closed && this.recoveryLeases.get(lease.transferId) === lease) {
+                const requestedEpoch = this.recoveryRequestedEpoch.get(lease.transferId);
+                const routeGenerationId = randomId();
+                try {
+                    const response = await this.request("transfer.resume", {
+                        transfer_id: lease.transferId,
+                        plan_fingerprint: lease.planFingerprint,
+                        coordinate_checksum: lease.coordinateChecksum,
+                        route_generation_id: routeGenerationId
+                    }, { transferId: lease.transferId, idempotencyKey: `transfer:${lease.transferId}:resume:${routeGenerationId}` });
+                    if (response.recovery === "terminal") {
+                        this.releaseRecoveryLease(lease.transferId);
+                        if (this.recoveryOperations.get(lease.transferId) === operation) {
+                            this.recoveryOperations.delete(lease.transferId);
+                        }
+                        return;
+                    }
+                    if (response.route_replay_required || response.recovery === "route_replay_required") {
+                        await lease.replayRoutes(routeGenerationId);
+                    }
+                    if (this.recoveryRequestedEpoch.get(lease.transferId) !== requestedEpoch) {
+                        attempt = 0;
+                        continue;
+                    }
+                    if (this.recoveryOperations.get(lease.transferId) === operation) {
+                        this.recoveryOperations.delete(lease.transferId);
+                    }
+                    return;
+                }
+                catch (error) {
+                    if (!isRetryableLifecycleError(error)) {
+                        this.releaseRecoveryLease(lease.transferId);
+                        return;
+                    }
+                    attempt += 1;
+                    await sleepWithJitter(Math.min(30_000, 500 * (2 ** Math.min(attempt, 6))));
+                }
+            }
+        })().finally(() => {
+            if (this.recoveryOperations.get(lease.transferId) === operation)
+                this.recoveryOperations.delete(lease.transferId);
+        });
+        this.recoveryOperations.set(lease.transferId, operation);
+        return operation;
+    }
     async resolveAuthToken() {
         const now = Math.floor(Date.now() / 1000);
         if (this.authToken && this.authTokenExpiresAt - 5 > now)
@@ -456,14 +616,22 @@ function randomId() {
     const cryptoApi = globalThis.crypto;
     if (cryptoApi?.randomUUID)
         return cryptoApi.randomUUID();
-    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    if (!cryptoApi?.getRandomValues)
+        throw new Error("secure UUID generation is unavailable");
+    const bytes = cryptoApi.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [...bytes].map((value) => value.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)}`;
 }
 const LIFECYCLE_REQUEST_MAX_ATTEMPTS = 3;
 const LIFECYCLE_REQUEST_RETRY_DELAYS_MS = [150, 500];
 function isRetryableLifecycleStatus(status) {
     return status === 408 || status === 425 || status === 429 || status >= 500;
 }
-function isRetryableLifecycleError(error) {
+export function isRetryableLifecycleError(error) {
+    if (error instanceof LifecycleRequestError)
+        return isRetryableLifecycleStatus(error.status);
     const record = error && typeof error === "object" ? error : null;
     const code = typeof record?.code === "string" ? record.code : "";
     const message = error instanceof Error ? error.message : String(error);
@@ -476,10 +644,19 @@ function isRetryableLifecycleError(error) {
         "econnreset",
         "econnrefused",
         "etimedout",
+        "fetch failed",
         "socket",
         "network"
     ].some((token) => combined.includes(token));
 }
+export function isRecoverableRouteStreamError(error) {
+    if (isRetryableLifecycleError(error))
+        return true;
+    if (error instanceof LifecycleRequestError)
+        return error.status === 404 || error.status === 409;
+    const status = error && typeof error === "object" ? Number(error.status) : NaN;
+    return status === 404 || status === 409;
+}
 async function sleepWithJitter(baseMs) {
     const jitter = Math.floor(baseMs * (Math.random() * 0.4 - 0.2));
     await new Promise((resolve) => setTimeout(resolve, Math.max(1, baseMs + jitter)));

package/dist/provider-signing.js

@@ -405,8 +405,7 @@ function s3CompatibleMetadata(source, endpoint = s3CompatibleEndpoint(source)) {
         key: source.key,
         region: s3CompatibleRegion(source),
         endpoint_url: endpoint,
-        account_id: "account_id" in source ? source.account_id : undefined,
-        capabilities: "capabilities" in source ? source.capabilities : undefined
+        account_id: "account_id" in source ? source.account_id : undefined
     });
 }
 function isHippiusProvider(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@beam-network/sdk",
-    "version": "0.4.4",
+    "version": "0.5.1",
     "description": "TypeScript SDK for BEAM transfer creation and management.",
     "type": "module",
     "license": "MIT",