@beam-network/sdk 0.5.21 → 0.6.1

package/README.md

@@ -1,5 +1,10 @@
 # BEAM SDK for TypeScript
 
+This release requires Core's `transfer-client-control/v7` contract. Multipart uploads use consecutive parts;
+Core may request retained staging for recovery through the existing SDK signing connection. Workers receive
+ordinary upload URLs. Keep the client connected until the transfer reaches a terminal state so Core can renew
+grants, promote recovered data, and clean up staging. Drain active transfers before upgrading Core and SDK consumers.
+
 Install:
 
 ```bash
@@ -149,21 +154,21 @@ For low-level raw transfer configs, use `createRawTransfer`; lifecycle transport
 
 ## Route Streaming And Payload Size
 
-Provider transfers use `transfer-client-control/v6`. 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. Hippius and Hugging Face destinations take a plain PUT per chunk instead, so they carry no multipart group manifest.
+Provider transfers use `transfer-client-control/v7`. 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. Hippius and Hugging Face destinations take a plain PUT per chunk instead, so they carry no multipart group manifest.
 
-The client signs up to 64 routes concurrently by default and emits 2,048-route logical batches. Encoded MessagePack requests target 4 MiB physical batches under `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. Lifecycle control refreshes cached SDK auth before the final 30 seconds of token lifetime and retries `auth_token_expired` replies with the same request identity and payload but a fresh token, preserving Core request-conflict protection during large route streams. A single route above the 4 MiB target but within the configured guard publishes alone; a single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
+The client signs up to 64 routes concurrently by default and emits 1,024-route logical batches. Encoded MessagePack requests target 4 MiB physical batches under `maxPayloadBytes` (8 MiB by default; explicit positive overrides remain supported). The splitter reserves control-envelope headroom for the live auth token and stable request identity so the final encoded request remains below the configured guard. Lifecycle control refreshes cached SDK auth before the final 30 seconds of token lifetime and retries `auth_token_expired` replies with the same request identity and payload but a fresh token, preserving Core request-conflict protection during large route streams. A single route above the 4 MiB target but within the configured guard publishes alone; a single route larger than the configured limit fails before publication with both sizes in the error. Multipart create and abort requests use a separate `multipartControlConcurrency` limit of 2 by default, with explicit positive overrides supported, and S3-compatible control requests make up to five attempts for transient provider failures. This keeps URL signing throughput independent from provider control-plane pressure.
 
 Callers that need durable recovery accounting can provide `onMultipartGroupReady`. The SDK invokes it after creating a multipart upload and before streaming that group’s signed routes. Its payload contains transfer, source, destination, object-key, upload, size, part-count, and expiry identities only; it never includes credentials, request headers, or signed URLs. A rejected callback aborts the newly created upload and fails preparation closed.
 
 `resumeProviderTransfer` requires the complete saved callback payloads in `multipartGroups`. It validates every transfer/source/destination/object/size/part coordinate, then uses the same route-stream implementation as creation with those upload IDs. Missing, duplicate, or changed identities fail before new provider uploads or route publication. If a process died before recording an upload identity, treat it as uncertain cleanup instead of inventing a replacement. The `onPrepared` callback also runs during resume, before routes are streamed.
 
-Create and resume accept an ownership `signal`. Aborting it stops initial routes, multipart creation, and recovery signing/replay; it does not cancel the transfer or abort a replacement owner's uploads. User cancellation still uses `cancelTransfer` and verified provider cleanup. `prepareProviderSource` accepts the same signal for metadata requests.
+Create and resume accept an ownership `signal`. Aborting it stops initial routes, multipart creation, and recovery signing/replay; it does not cancel the transfer or abort a replacement owner's uploads. Recovery leases, signers, and background resume/replay are keyed by owner identity: a fenced-off owner never replays into, releases, or stops the signers of a replacement owner registered for the same transfer, and a replacement always gets its own recovery. User cancellation still uses `cancelTransfer` and verified provider cleanup. `prepareProviderSource` accepts the same signal for metadata requests.
 
 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. A non-recoverable provider setup or route failure raises `BeamProviderTransferError`, whose `errors`, `transferCancelled`, and `multipartCleanupComplete` fields retain the original provider, cancellation, and cleanup outcomes. `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.
 
 During the pre-completion `integrity_check` phase, Runtime may include an `integrity_audit_challenge` in status. The TypeScript client signs exact read-only source and final-destination GET ranges and submits `transfer.integrity_audit_grants`. S3-compatible source and destination grants use the prepared source ETag and Runtime-verified final-object ETag as `If-Match` conditions. Submission failures retry on the next status poll and appear as a URL-safe `integrity_audit_submission_error` on that status response; the transfer completes with a warning if the check cannot finish by its deadline.
 
-Hippius uses canonical non-multipart `signed_url` routes, so its manifest is empty and group-level final HEAD verification is not available from that provider flow.
+Hippius uses canonical non-multipart `signed_url` routes (initial and recovered routes both PUT to the planned `<final>/<plan_nonce>/chunk-NNNNNN` key), 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.
 
@@ -184,3 +189,9 @@ Only short-lived range/upload routes go to workers. Multipart creation, verifica
 Manual releases from `dev` require a committed `-dev.N` version and publish only to npm tag `dev`; the stable tag is unchanged.
 
 Multipart control helpers (`createMultipartUpload`, `listMultipartParts`, `completeMultipartUpload`, `inspectDestinationObject`, and `abortMultipartUpload`) accept an optional `AbortSignal` and cancel through the existing provider HTTP transport. Pass it as `signal` in object arguments or as the last positional argument. Cancellation stops waiting and network activity; it cannot undo a provider operation already accepted. After an interrupted completion, inspect the durable upload/object identity before retrying or reporting cleanup complete.
+
+### Preparation diagnostics
+
+Route streaming flushes at 1,024 routes, with no timer, and sends the final partial batch at stream completion. Signing overlaps acknowledged publication through bounded buffering; existing encoded-payload limits still apply. A source grant is reused across destinations only within the same signing generation and actual expiry.
+
+The optional `onDiagnostics` callback receives bounded preparation measurements and source-grant reuse counts. Callbacks are best effort, may be dropped under load, and do not affect transfer outcomes. Durations may overlap; do not sum them into elapsed transfer time. Transfer status also exposes a typed `performance` summary when supported by Core.

package/dist/client.d.ts

@@ -44,8 +44,11 @@ export declare class BeamClient {
     private readonly routeSigningConcurrency;
     private readonly routeSigningConcurrencyOverridden;
     private readonly multipartControlConcurrency;
+    private readonly onDiagnostics;
+    private diagnosticPending;
     private readonly recoverySigners;
     private readonly integrityAuditSigners;
+    private readonly integrityGrantCache;
     private readonly integrityAuditSubmissions;
     private readonly huggingFaceUploads;
     constructor(options?: BeamClientOptions);
@@ -105,7 +108,9 @@ export declare class BeamClient {
     private startProviderRouteRecoverySigner;
     private recoveryMultipartUploadState;
     private submitIntegrityAuditGrantsIfPresent;
-    private submitProviderIntegrityAuditGrants;
+    private signedIntegrityGrants;
+    private buildProviderIntegrityAuditGrants;
+    /** Stop a transfer's recovery and integrity signers; with `owner`, only if that owner installed them. */
     private stopRecoverySigner;
     private stopAllRecoverySigners;
     createAndDistribute(input: RawTransferCreateInput): Promise<TransferCreateResponse>;

package/dist/client.js

@@ -1,4 +1,5 @@
-import { abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationReadRange, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signSourceReadRange, isHuggingFaceProvider } from "./provider-signing.js";
+import { SdkPerformanceCollector } from "./performance.js";
+import { signMultipartRecovery, abortMultipartUpload, createMultipartUpload, expiresAtIso, prepareProviderDestination, prepareProviderSource, releaseProviderClients, signAbortMultipartUpload, signCompleteMultipartUpload, signDestinationReadRange, signDestinationRoute, signFinalObjectHead, signListMultipartUpload, signSourceReadRange, signSourceChunk, boundedGrantExpiry, isHuggingFaceProvider } from "./provider-signing.js";
 import { describe as describeHuggingFace, hashSourceStream, huggingFaceCommit, huggingFaceCompleteLfsUpload, huggingFaceLfsBatch, huggingFacePreupload, huggingFaceVerifyLfsUpload, readSourceSample } from "./huggingface.js";
 import { BeamTransferControl, BEAM_DEFAULT_NATS_URL, compactSignedRoutes, isRecoverableRouteStreamError } from "./nats-control.js";
 export class BeamRouteRecoveryPendingError extends Error {
@@ -53,11 +54,15 @@ export class BeamClient {
     routeSigningConcurrency;
     routeSigningConcurrencyOverridden;
     multipartControlConcurrency;
+    onDiagnostics;
+    diagnosticPending = false;
     recoverySigners = new Map();
     integrityAuditSigners = new Map();
+    integrityGrantCache = new Map();
     integrityAuditSubmissions = new Map();
     huggingFaceUploads = new Map();
     constructor(options = {}) {
+        this.onDiagnostics = options.onDiagnostics;
         if (!options.apiKey?.trim()) {
             throw new Error("apiKey is required.");
         }
@@ -237,7 +242,7 @@ export class BeamClient {
         };
         const routeStreamLock = new AsyncMutex();
         const releaseInitialStream = await routeStreamLock.acquire();
-        this.control.registerRecoveryLease({
+        const recoveryLease = {
             transferId,
             planFingerprint: input.planFingerprint,
             coordinateChecksum: input.coordinateChecksum,
@@ -249,19 +254,20 @@ export class BeamClient {
                         throw new Error(attached.error ?? attached.message ?? "route replay failed");
                 });
             }
-        });
+        };
+        this.control.registerRecoveryLease(recoveryLease);
         try {
             const attached = await streamRoutes(input.chunkRoutes, input.multipartGroupManifest, input.routeGenerationId, input.urlsExpiresAt);
             if (!attached.success)
-                this.control.releaseRecoveryLease(transferId);
+                this.control.releaseRecoveryLease(transferId, recoveryLease);
             return attached;
         }
         catch (error) {
             if (isRecoverableRouteStreamError(error)) {
-                this.control.continueRecoveryLease(transferId);
+                this.control.continueRecoveryLease(transferId, recoveryLease);
                 throw new BeamRouteRecoveryPendingError(transferId, error);
             }
-            this.control.releaseRecoveryLease(transferId);
+            this.control.releaseRecoveryLease(transferId, recoveryLease);
             throw error;
         }
         finally {
@@ -294,8 +300,10 @@ export class BeamClient {
             destinationsById.set(preparedDestination.destination_id, destination);
         });
         await input.throwIfCancelled?.();
+        const discoveryStarted = performance.now();
         const preparedSources = await Promise.all(retainedRecoveryInput.sources.map((source, index) => prepareProviderSource(source, { index, expiresIn, fetchImpl: this.fetchImpl, signal: input.signal })));
         await input.throwIfCancelled?.();
+        const discoveryMs = performance.now() - discoveryStarted;
         const huggingFace = await this.planHuggingFaceUploads({
             sources: retainedRecoveryInput.sources,
             preparedSources,
@@ -346,6 +354,9 @@ export class BeamClient {
         const routeStreamLock = new AsyncMutex();
         const releaseInitialStream = await routeStreamLock.acquire();
         const streamPreparedRoutes = async (routeGenerationId, recoveryReplay) => {
+            const telemetry = new SdkPerformanceCollector();
+            if (!recoveryReplay)
+                telemetry.observe("sdk.discovery", discoveryMs);
             const pendingRoutes = new Set();
             let signingConcurrency = this.routeSigningConcurrency;
             let signedInWindow = 0;
@@ -376,6 +387,15 @@ export class BeamClient {
                     signedUrlFlow: requestedSignedUrlFlow
                 });
                 routeStream = new RouteStreamSender(this.control, {
+                    telemetry,
+                    onDiagnostics: (summary) => {
+                        if (!this.onDiagnostics || this.diagnosticPending)
+                            return;
+                        this.diagnosticPending = true;
+                        setTimeout(() => {
+                            void Promise.resolve().then(() => this.onDiagnostics?.(summary)).catch(() => { }).finally(() => { this.diagnosticPending = false; });
+                        }, 0);
+                    },
                     streamId,
                     transferId: prepared.transfer_id,
                     routeGenerationId,
@@ -388,7 +408,7 @@ export class BeamClient {
                 routeStreamBeginAttempted = true;
                 await routeStream.begin();
                 multipartGroupWaiters = createMultipartGroupWaiters(prepared, destinationsById);
-                multipartManifestTask = createMultipartGroupManifest({
+                multipartManifestTask = telemetry.measure("sdk.multipart_create", () => createMultipartGroupManifest({
                     prepared,
                     destinationsById,
                     multipartUploads,
@@ -405,7 +425,7 @@ export class BeamClient {
                         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);
@@ -423,6 +443,12 @@ export class BeamClient {
                 };
                 for (const chunk of materializePlanChunks(prepared.plan_descriptor, prepared.transfer_id)) {
                     await throwIfCancelled?.(prepared.transfer_id);
+                    // This promise belongs to this chunk and signing generation only. Its
+                    // immutable credential/range identity and actual expiry cannot be renewed.
+                    const sourceGrant = signSourceChunk({ source: sourcesById.get(chunk.source_id), fallbackUrl: chunk.source_url, chunk, expiresIn, fetchImpl: this.fetchImpl });
+                    void sourceGrant.catch(() => { });
+                    telemetry.counters.source_signatures++;
+                    telemetry.counters.source_reuses += Math.max(0, chunk.destinations.length - 1);
                     for (const target of chunk.destinations) {
                         const pendingRoute = (async () => {
                             await throwIfCancelled?.(prepared.transfer_id);
@@ -442,10 +468,11 @@ export class BeamClient {
                                 : await multipartGroupWaiters.get(multipartGroupId)?.promise;
                             if (!isDirectPutDestination(destination) && !upload)
                                 throw new Error(`multipart group manifest is missing for ${chunk.source_id}:${target.destination_id}`);
-                            return this.signProviderRoute({
+                            return telemetry.measure("sdk.signing", () => this.signProviderRoute({
                                 chunk,
                                 target,
                                 source,
+                                sourceGrant,
                                 destination,
                                 expiresIn,
                                 ...(upload ? { upload } : {}),
@@ -456,7 +483,7 @@ export class BeamClient {
                                 partNumber: typeof metadata.part_number === "number"
                                     ? metadata.part_number
                                     : multipartPartNumber(chunk.source_chunk_index),
-                            });
+                            }));
                         })();
                         pendingRoutes.add(pendingRoute);
                         if (pendingRoutes.size >= signingConcurrency)
@@ -475,8 +502,8 @@ export class BeamClient {
             }
             catch (error) {
                 if (input.signal?.aborted) {
-                    this.stopRecoverySigner(prepared.transfer_id);
-                    this.control.releaseRecoveryLease(prepared.transfer_id);
+                    this.stopRecoverySigner(prepared.transfer_id, recoveryLease);
+                    this.control.releaseRecoveryLease(prepared.transfer_id, recoveryLease);
                     await Promise.allSettled(pendingRoutes);
                     if (multipartManifestTask)
                         await Promise.allSettled([multipartManifestTask]);
@@ -489,10 +516,10 @@ export class BeamClient {
                     await Promise.allSettled([multipartManifestTask]);
                 if (!recoveryReplay) {
                     if (foregroundCancelled) {
-                        this.control.continueRecoveryLease(prepared.transfer_id);
+                        this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                     }
                     else if (isRecoverableRouteStreamError(error)) {
-                        this.control.continueRecoveryLease(prepared.transfer_id);
+                        this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                         throw new BeamRouteRecoveryPendingError(prepared.transfer_id, error);
                     }
                     else {
@@ -510,27 +537,16 @@ export class BeamClient {
                             // The retained recovery input owns the same destination objects used by
                             // multipart cleanup. Releasing it earlier scrubs their scoped credentials
                             // before abortMultipartUpload can clean up already-created uploads.
-                            this.control.releaseRecoveryLease(prepared.transfer_id);
+                            this.control.releaseRecoveryLease(prepared.transfer_id, recoveryLease);
                         }
                     }
                 }
                 throw error;
             }
         };
-        await this.startProviderRouteRecoverySigner({
-            prepared,
-            sourcesById,
-            destinationsById,
-            multipartUploads: recoveryMultipartUploads,
-            signal: input.signal,
-            expiresIn
-        });
-        const stopOwnedRecovery = () => {
-            this.stopRecoverySigner(prepared.transfer_id);
-            this.control.releaseRecoveryLease(prepared.transfer_id);
-        };
-        input.signal?.addEventListener("abort", stopOwnedRecovery, { once: true });
-        this.control.registerRecoveryLease({
+        // The lease object is this owner's identity: releases, recovery requests, and
+        // signer shutdowns below only act while it is still the registered lease.
+        const recoveryLease = {
             transferId: prepared.transfer_id,
             planFingerprint: prepared.plan_fingerprint,
             coordinateChecksum: prepared.coordinate_checksum,
@@ -539,23 +555,39 @@ export class BeamClient {
             },
             disposeSecrets: () => {
                 input.signal?.removeEventListener("abort", stopOwnedRecovery);
+                releaseProviderClients([...retainedRecoveryInput.sources, ...retainedRecoveryInput.destinations]);
                 clearRecoverySecrets(retainedRecoveryInput);
             }
+        };
+        await this.startProviderRouteRecoverySigner({
+            owner: recoveryLease,
+            prepared,
+            sourcesById,
+            destinationsById,
+            multipartUploads: recoveryMultipartUploads,
+            signal: input.signal,
+            expiresIn
         });
+        const stopOwnedRecovery = () => {
+            this.stopRecoverySigner(prepared.transfer_id, recoveryLease);
+            this.control.releaseRecoveryLease(prepared.transfer_id, recoveryLease);
+        };
+        input.signal?.addEventListener("abort", stopOwnedRecovery, { once: true });
+        this.control.registerRecoveryLease(recoveryLease);
         try {
             try {
                 assertOwnership();
                 await input.onPrepared?.(prepared);
             }
             catch (error) {
-                this.control.continueRecoveryLease(prepared.transfer_id);
+                this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                 throw error;
             }
             try {
                 await input.throwIfCancelled?.(prepared.transfer_id);
             }
             catch (error) {
-                this.control.continueRecoveryLease(prepared.transfer_id);
+                this.control.continueRecoveryLease(prepared.transfer_id, recoveryLease);
                 throw error;
             }
             await streamPreparedRoutes(prepared.route_generation_id, false);
@@ -740,6 +772,7 @@ export class BeamClient {
                     metadata: directPutRouteMetadata(input.target.metadata)
                 },
                 source: input.source,
+                sourceGrant: input.sourceGrant,
                 destination: input.destination,
                 expiresIn: input.expiresIn,
                 destUrl,
@@ -751,6 +784,7 @@ export class BeamClient {
                 chunk: input.chunk,
                 target: { ...input.target, metadata: partRouteMetadata(input.target.metadata) },
                 source: input.source,
+                sourceGrant: input.sourceGrant,
                 destination: input.destination,
                 expiresIn: input.expiresIn,
                 fetchImpl: this.fetchImpl
@@ -768,6 +802,7 @@ export class BeamClient {
                 metadata: partRouteMetadata(input.target.metadata)
             },
             source: input.source,
+            sourceGrant: input.sourceGrant,
             destination: input.destination,
             expiresIn: input.expiresIn,
             uploadId: upload.uploadId,
@@ -791,6 +826,7 @@ export class BeamClient {
             input.signal?.throwIfAborted();
             if (payload.route_generation_id.length === 0)
                 throw new Error("route recovery generation is required");
+            const sourceGrants = new Map();
             const routes = await mapOrderedWithConcurrency(payload.chunks, this.routeSigningConcurrency, async (requested) => {
                 input.signal?.throwIfAborted();
                 if (requested.route_generation_id !== payload.route_generation_id) {
@@ -821,11 +857,22 @@ export class BeamClient {
                         multipartUploads: input.multipartUploads,
                         expiresIn: input.expiresIn
                     });
-                return this.signProviderRoute({
+                const sourceKey = JSON.stringify([chunk.source_id, chunk.chunk_index]);
+                let sourceGrant = sourceGrants.get(sourceKey);
+                if (!sourceGrant) {
+                    sourceGrant = signSourceChunk({ source, chunk, fallbackUrl: chunk.source_url, expiresIn: input.expiresIn, fetchImpl: this.fetchImpl });
+                    sourceGrants.set(sourceKey, sourceGrant);
+                    void sourceGrant.catch(() => { });
+                }
+                const route = await this.signProviderRoute({
+                    sourceGrant,
                     chunk,
                     target: {
                         ...target,
-                        object_key: requested.final_object_key,
+                        // Direct-PUT destinations (Hippius, Hugging Face) keep the planned
+                        // per-chunk key exactly as initial materialization does; only
+                        // multipart destinations sign parts against the final object key.
+                        object_key: isDirectPutDestination(destination) ? target.object_key : requested.final_object_key,
                         metadata: {
                             ...(target.metadata ?? {}),
                             ...(requested.destination_metadata ?? {}),
@@ -852,6 +899,7 @@ export class BeamClient {
                     signedUrlFlow: "signed_url",
                     partNumber: requested.part_number
                 });
+                return signMultipartRecovery({ destination, transferId: input.prepared.transfer_id, requested, route, expiresIn: input.expiresIn });
             });
             return {
                 transfer_id: payload.transfer_id,
@@ -860,16 +908,33 @@ export class BeamClient {
                 chunk_routes: routes
             };
         });
-        this.recoverySigners.set(input.prepared.transfer_id, stop);
-        this.integrityAuditSigners.set(input.prepared.transfer_id, async (challenge) => {
-            await this.submitProviderIntegrityAuditGrants({
-                challenge,
-                prepared: input.prepared,
-                sourcesById: input.sourcesById,
-                destinationsById: input.destinationsById,
-                expiresIn: input.expiresIn
+        if (input.signal?.aborted) {
+            stop();
+            return;
+        }
+        this.stopRecoverySigner(input.prepared.transfer_id);
+        this.integrityAuditSigners.set(input.prepared.transfer_id, (challenge) => this.buildProviderIntegrityAuditGrants({
+            challenge, prepared: input.prepared, sourcesById: input.sourcesById, destinationsById: input.destinationsById, expiresIn: input.expiresIn
+        }));
+        const registration = { owner: input.owner, stop };
+        this.recoverySigners.set(input.prepared.transfer_id, registration);
+        try {
+            const stopIntegrity = await this.control.serveIntegritySigner(input.prepared.transfer_id, challenge => {
+                input.signal?.throwIfAborted();
+                return this.signedIntegrityGrants(challenge);
             });
-        });
+            if (input.signal?.aborted || this.recoverySigners.get(input.prepared.transfer_id) !== registration) {
+                stop();
+                stopIntegrity();
+                return;
+            }
+            registration.stop = () => { stop(); stopIntegrity(); };
+        }
+        catch {
+            // Status-driven signing remains available if the optional subscription fails.
+            if (input.signal?.aborted)
+                this.stopRecoverySigner(input.prepared.transfer_id, input.owner);
+        }
     }
     async recoveryMultipartUploadState(input) {
         const existing = input.multipartUploads.get(input.requested.multipart_group_id);
@@ -936,21 +1001,56 @@ export class BeamClient {
         if (!signer)
             throw new Error("integrity audit signer unavailable");
         const existing = this.integrityAuditSubmissions.get(challenge.audit_id);
-        if (existing) {
+        const cached = this.integrityGrantCache.get(challenge.audit_id);
+        if (cached && cached.fingerprint !== JSON.stringify(challenge))
+            throw new Error("integrity audit identity changed");
+        if (existing && cached && cached.expiresAt > Date.now() + 30_000) {
             await existing;
             return;
         }
-        const submission = signer(challenge);
+        const submission = this.signedIntegrityGrants(challenge).then(async (payload) => {
+            const result = await this.control.request("transfer.integrity_audit_grants", payload, {
+                transferId: challenge.transfer_id, idempotencyKey: `transfer:${challenge.transfer_id}:integrity-audit:${challenge.audit_id}:${payload.submitted_at}`
+            });
+            if (result.published !== true)
+                throw new Error("integrity audit delivery unavailable");
+        });
         this.integrityAuditSubmissions.set(challenge.audit_id, submission);
         try {
             await submission;
         }
         catch (error) {
-            this.integrityAuditSubmissions.delete(challenge.audit_id);
+            if (this.integrityAuditSubmissions.get(challenge.audit_id) === submission)
+                this.integrityAuditSubmissions.delete(challenge.audit_id);
             throw error;
         }
     }
-    async submitProviderIntegrityAuditGrants(input) {
+    signedIntegrityGrants(challenge) {
+        const fingerprint = JSON.stringify(challenge);
+        const cached = this.integrityGrantCache.get(challenge.audit_id);
+        if (cached && cached.fingerprint !== fingerprint)
+            return Promise.reject(new Error("integrity audit identity changed"));
+        if (cached && cached.expiresAt > Date.now() + 30_000)
+            return cached.payload;
+        if (!cached && this.integrityGrantCache.size >= 1024)
+            return Promise.reject(new Error("integrity signer capacity unavailable"));
+        const signer = this.integrityAuditSigners.get(challenge.transfer_id);
+        if (!signer)
+            return Promise.reject(new Error("integrity audit signer unavailable"));
+        this.integrityAuditSubmissions.delete(challenge.audit_id);
+        const entry = { transferId: challenge.transfer_id, expiresAt: 0, fingerprint, payload: Promise.resolve({}) };
+        entry.payload = signer(challenge).then(payload => {
+            const chunks = payload.chunks;
+            entry.expiresAt = Math.min(...chunks.flatMap(chunk => [Date.parse(chunk.source.expires_at), Date.parse(chunk.destination.expires_at)]));
+            return payload;
+        }).catch(error => { if (this.integrityGrantCache.get(challenge.audit_id) === entry)
+            this.integrityGrantCache.delete(challenge.audit_id); throw error; });
+        // Pending grants are shared too. Actual expiry replaces this sentinel on completion.
+        entry.expiresAt = Infinity;
+        this.integrityGrantCache.set(challenge.audit_id, entry);
+        return entry.payload;
+    }
+    async buildProviderIntegrityAuditGrants(input) {
         if (input.challenge.transfer_id !== input.prepared.transfer_id) {
             throw new Error("integrity audit challenge transfer mismatch");
         }
@@ -977,6 +1077,7 @@ export class BeamClient {
             }
             const sourceEtag = plannedSource?.metadata?.etag;
             const sourceVersionId = plannedSource?.metadata?.version_id;
+            const grantExpiresAt = new Date(Math.floor(Date.now() / 1000) * 1000 + input.expiresIn * 1000).toISOString();
             const [sourceGrant, destinationGrant] = await Promise.all([
                 signSourceReadRange({
                     source,
@@ -997,31 +1098,30 @@ export class BeamClient {
                     fetchImpl: this.fetchImpl
                 })
             ]);
-            const grantExpiresAt = expiresAtIso(input.expiresIn);
             const { orchestrator_id: _orchestratorId, orchestrator_hotkey: _orchestratorHotkey, worker_id: _workerId, ...grantChunk } = chunk;
             return {
                 ...grantChunk,
-                source: { ...sourceGrant, expires_at: grantExpiresAt },
-                destination: { ...destinationGrant, expires_at: grantExpiresAt }
+                source: { ...sourceGrant, expires_at: boundedGrantExpiry(sourceGrant.url, grantExpiresAt) },
+                destination: { ...destinationGrant, expires_at: boundedGrantExpiry(destinationGrant.url, grantExpiresAt) }
             };
         });
-        await this.control.request("transfer.integrity_audit_grants", {
-            transfer_id: input.challenge.transfer_id,
-            audit_id: input.challenge.audit_id,
-            submitted_at: submittedAt,
-            chunks
-        }, {
-            transferId: input.challenge.transfer_id,
-            idempotencyKey: `transfer:${input.challenge.transfer_id}:integrity-audit:${input.challenge.audit_id}`
-        });
+        return { transfer_id: input.challenge.transfer_id, audit_id: input.challenge.audit_id, submitted_at: submittedAt, chunks };
     }
-    stopRecoverySigner(transferId) {
-        const stop = this.recoverySigners.get(transferId);
-        if (stop) {
-            stop();
+    /** Stop a transfer's recovery and integrity signers; with `owner`, only if that owner installed them. */
+    stopRecoverySigner(transferId, owner) {
+        const signer = this.recoverySigners.get(transferId);
+        if (owner && signer?.owner !== owner)
+            return;
+        if (signer) {
+            signer.stop();
             this.recoverySigners.delete(transferId);
         }
         this.integrityAuditSigners.delete(transferId);
+        for (const [auditId, entry] of this.integrityGrantCache)
+            if (entry.transferId === transferId) {
+                this.integrityGrantCache.delete(auditId);
+                this.integrityAuditSubmissions.delete(auditId);
+            }
     }
     stopAllRecoverySigners() {
         for (const transferId of [...this.recoverySigners.keys()])
@@ -1117,7 +1217,7 @@ export class BeamClient {
         }
     }
 }
-const ROUTE_STREAM_BATCH_ROUTES = 2_048;
+const ROUTE_STREAM_BATCH_ROUTES = 1_024;
 class AsyncMutex {
     tail = Promise.resolve();
     async acquire() {
@@ -1142,6 +1242,8 @@ class AsyncMutex {
 class RouteStreamSender {
     control;
     options;
+    started = performance.now();
+    telemetry;
     streamId;
     checksum = new RouteKeysChecksum();
     batch = [];
@@ -1154,6 +1256,7 @@ class RouteStreamSender {
         this.control = control;
         this.options = options;
         this.streamId = options.streamId;
+        this.telemetry = options.telemetry ?? new SdkPerformanceCollector();
     }
     async begin() {
         await this.control.request("transfer.route_stream.begin", compact({
@@ -1215,7 +1318,11 @@ class RouteStreamSender {
         await this.sendTail;
         if (this.sendError)
             throw this.sendError;
+        this.telemetry.observe("sdk.preparation", performance.now() - this.started);
+        const sdkPerformance = this.telemetry.snapshot();
+        this.options.onDiagnostics?.(sdkPerformance);
         return this.control.request("transfer.route_stream.complete", {
+            sdk_performance: sdkPerformance,
             transfer_id: this.options.transferId,
             route_generation_id: this.options.routeGenerationId,
             stream_id: this.streamId,
@@ -1230,7 +1337,7 @@ class RouteStreamSender {
     async enqueueFlush() {
         if (!this.batch.length)
             return;
-        await this.sendTail;
+        await this.telemetry.measure("sdk.buffer_wait", () => this.sendTail);
         if (this.sendError)
             throw this.sendError;
         const routes = this.batch.splice(0, this.batch.length);
@@ -1254,7 +1361,8 @@ class RouteStreamSender {
                     const routeChecksum = chunkChecksum.value();
                     const coordinateChecksum = await routeCoordinateChecksum(chunk);
                     const batchId = `${this.streamId}:${batchIndex}:${coordinateChecksum}`;
-                    await this.control.request("transfer.route_stream.batch", {
+                    this.telemetry.counters.route_batches++;
+                    await this.telemetry.measure("sdk.batch_ack", () => this.control.request("transfer.route_stream.batch", {
                         transfer_id: this.options.transferId,
                         route_generation_id: this.options.routeGenerationId,
                         stream_id: this.streamId,
@@ -1266,7 +1374,7 @@ class RouteStreamSender {
                     }, {
                         transferId: this.options.transferId,
                         idempotencyKey: `transfer:${this.options.transferId}:route-stream:${this.streamId}:batch:${batchIndex}:${coordinateChecksum}`
-                    });
+                    }));
                 }
                 catch (error) {
                     this.sendError = error;
@@ -1510,6 +1618,9 @@ function createDeferred() {
         resolve = resolvePromise;
         reject = rejectPromise;
     });
+    // A waiter may be rejected after its route loop already stopped (for example when
+    // ownership is fenced mid-stream); awaiting callers still observe the rejection.
+    promise.catch(() => undefined);
     return { promise, resolve, reject };
 }
 function createMultipartGroupWaiters(prepared, destinationsById) {
@@ -1661,7 +1772,7 @@ function multipartListPageMarkers(maxPartNumber) {
     return markers;
 }
 function multipartMaxPartNumber(chunkCount) {
-    return multipartPartNumber(positiveInteger(chunkCount, "source chunk_count") - 1, 2);
+    return multipartPartNumber(positiveInteger(chunkCount, "source chunk_count") - 1);
 }
 function validateMultipartPartNumber(partNumber, manifest) {
     if (!Number.isInteger(partNumber) || partNumber < 1 || partNumber > manifest.max_part_number) {
@@ -1715,7 +1826,7 @@ const COMPACT_TRANSFER_PLAN_KEYS = new Set([
 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 * 3 + attempt_slot + 1",
+    part_number: "source_chunk_index + 1",
     route_generation_id: "initial-{chunk_index}-{destination_id}"
 };
 function validateCompactTransferPlan(descriptor, signedUrlFlow) {
@@ -1729,7 +1840,7 @@ function validateCompactTransferPlan(descriptor, signedUrlFlow) {
     if (descriptor.version !== "compact-transfer-plan/v1") {
         throw new Error(`BeamCore returned unsupported plan version: ${descriptor.version}`);
     }
-    if (descriptor.multipart_attempt_slots !== 3) {
+    if (descriptor.multipart_attempt_slots !== 1) {
         throw new Error("BeamCore returned unsupported multipart attempt slot count");
     }
     const formulaKeys = Object.keys(descriptor.formulas);
@@ -1782,7 +1893,7 @@ function validateMultipartGroupManifest(manifest, transferId) {
         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 (!Number.isInteger(group.max_part_number) || group.max_part_number < group.expected_part_count || group.max_part_number > 10_000) {
+        if (!Number.isInteger(group.max_part_number) || group.max_part_number !== group.expected_part_count || group.max_part_number > 10_000) {
             throw new Error(`multipart group ${group.multipart_group_id} has invalid max_part_number`);
         }
         if (!Number.isSafeInteger(group.expected_object_size) || group.expected_object_size <= 0) {
@@ -1810,7 +1921,8 @@ const PART_ROUTE_METADATA_KEYS = new Set([
     "logical_attempt_index",
     "attempt_slot",
     "route_generation_id",
-    "delivery_index"
+    "delivery_index",
+    "etag_required"
 ]);
 function partRouteMetadata(metadata) {
     return Object.fromEntries(Object.entries(metadata ?? {}).filter(([key]) => PART_ROUTE_METADATA_KEYS.has(key)));