openrtc-file-transfer 2.9.7 → 3.0.0

package/dist/index.js

@@ -1,3 +1,13 @@
+import { requiredTransferCapabilities, withRequiredCapabilities, requiredCapabilities, transferCapabilities, requireCapabilities, MAX_CAPABILITY_BYTES, LEGACY_MAX_FILE_BYTES } from './capabilities.js';
+export { requiredTransferCapabilities, withRequiredCapabilities, REQUIRED_CAPABILITIES_METADATA_KEY, LEGACY_MAX_FILE_BYTES } from './capabilities.js';
+import { sha256 as incrementalSha256 } from '@noble/hashes/sha256';
+/** Checkpoint-before-offset and product-commit-before-completion semantics. */
+export const DURABLE_DELIVERY_VERSION = 1;
+/** Per-sink body policy, legacy admission and execution cancellation. */
+export const BULK_RECEIVE_FLOW_CONTROL_VERSION = 1;
+export const BULK_RECEIVE_ADMISSION_WAIT_VERSION = 1;
+/** Unpaced stream/v1 sink policy and idle execution retirement. */
+export const BULK_STREAM_RECEIVE_FLOW_CONTROL_VERSION = 1;
 /**
  * Transitional adapter for advanced native hosts that obtain a low-level
  * runtime through `runtimeFromCapability()`. The file-transfer package owns
@@ -108,8 +118,24 @@ const ROUTED_KIND_ACK = 0x04;
 const ROUTED_KIND_COMPLETE = 0x05;
 const ROUTED_KIND_COMPLETED = 0x06;
 const ROUTED_KIND_REJECT = 0x07;
+const ROUTED_KIND_WAITING = 0x08;
+const ROUTED_KIND_CAPABILITIES_REQUEST = 0x09;
+const ROUTED_KIND_CAPABILITIES = 0x0a;
+export const RECEIVER_WAIT_METADATA_KEY = 'openrtc.receive-wait';
+export const MAX_RECEIVER_WAIT_LEASE_MS = 60000;
+const DEFAULT_RECEIVER_WAIT_LEASE_MS = 10000;
+/** Persist this capability as part of the immutable offer before acceptance. */
+export function withReceiverWaitCapability(header) {
+    return { ...header, metadata: { ...header.metadata, [RECEIVER_WAIT_METADATA_KEY]: '1' } };
+}
+function supportsReceiverWait(header) {
+    return header.metadata?.[RECEIVER_WAIT_METADATA_KEY] === '1';
+}
 const DEFAULT_ROUTED_CHUNK_BYTES = 48 * 1024;
 const DEFAULT_ROUTED_WINDOW_CHUNKS = 8;
+export const MAX_TRANSFER_CHUNK_BYTES = 64 * 1024;
+export const MAX_TRANSFER_WINDOW_CHUNKS = 64;
+const MAX_PROTOCOL_RECOVERY_ATTEMPTS = 32;
 const MAX_ROUTED_TRANSFER_ID_BYTES = 512;
 function routedDebug(message, data) {
     let enabled = globalThis.__OPENRTC_DEBUG__ === true;
@@ -121,11 +147,23 @@ function routedDebug(message, data) {
         console.info(`[OpenRTC][file-transfer] ${message}`, data);
     }
 }
+export { BulkFlowController } from './flowControl.js';
+export const BULK_SEND_FLOW_CONTROL_VERSION = 1;
+export const BULK_JOB_FLOW_CONTROL_VERSION = 1;
+export const BULK_SCOPED_FLOW_CONTROL_VERSION = 1;
 function routedTransferId(frame) {
     return frame.kind === 'offer' ? frame.header.transferId : frame.transferId;
 }
 class TransferRejectedError extends Error {
 }
+// A product policy wait/rejection is not an ambiguous route send. Preserve its
+// original typed error and leave the next application retry to the queue owner.
+class TransferBodyAdmissionFailure extends Error {
+    constructor(failure) {
+        super(failure instanceof Error ? failure.message : String(failure));
+        this.failure = failure;
+    }
+}
 function writeU64(view, offset, value) {
     if (!Number.isSafeInteger(value) || value < 0)
         throw new Error('routed transfer offset is invalid');
@@ -146,6 +184,21 @@ export function encodeFrame(frame, maxHeaderBytes = DEFAULT_MAX_HEADER_BYTES, ma
     let kind;
     let body;
     switch (frame.kind) {
+        case 'capabilities-request':
+        case 'capabilities': {
+            kind = frame.kind === 'capabilities-request' ? ROUTED_KIND_CAPABILITIES_REQUEST : ROUTED_KIND_CAPABILITIES;
+            if (frame.kind === 'capabilities-request' && frame.header && frame.header.transferId !== transferId)
+                throw new Error('capability probe transferId mismatch');
+            const payload = frame.kind === 'capabilities-request'
+                ? frame.header ? encodeHeader(frame.header, maxHeaderBytes).subarray(4) : new Uint8Array()
+                : new TextEncoder().encode(JSON.stringify(transferCapabilities(frame.capabilities)));
+            if (payload.byteLength > (frame.kind === 'capabilities' ? MAX_CAPABILITY_BYTES : maxHeaderBytes))
+                throw new Error('transfer capability frame is too large');
+            body = new Uint8Array(4 + payload.byteLength);
+            new DataView(body.buffer).setUint32(0, payload.byteLength, false);
+            body.set(payload, 4);
+            break;
+        }
         case 'offer': {
             kind = ROUTED_KIND_OFFER;
             const header = new TextEncoder().encode(JSON.stringify(frame.header));
@@ -168,6 +221,15 @@ export function encodeFrame(frame, maxHeaderBytes = DEFAULT_MAX_HEADER_BYTES, ma
             writeU64(new DataView(body.buffer), 0, frame.kind === 'resume' || frame.kind === 'ack' ? frame.offset : frame.size);
             break;
         }
+        case 'waiting': {
+            kind = ROUTED_KIND_WAITING;
+            if (!Number.isSafeInteger(frame.leaseMs) || frame.leaseMs < 1 || frame.leaseMs > MAX_RECEIVER_WAIT_LEASE_MS)
+                throw new Error('invalid receiver wait lease');
+            body = new Uint8Array(12);
+            writeU64(new DataView(body.buffer), 0, frame.offset);
+            new DataView(body.buffer).setUint32(8, frame.leaseMs, false);
+            break;
+        }
         case 'chunk': {
             kind = ROUTED_KIND_CHUNK;
             if (!frame.bytes.byteLength || frame.bytes.byteLength > maxChunkBytes) {
@@ -210,6 +272,21 @@ export function decodeFrame(input, maxFileBytes = DEFAULT_MAX_BUFFERED_FILE_BYTE
     const transferId = new TextDecoder().decode(input.slice(7, 7 + idLength));
     const body = input.slice(7 + idLength);
     const bodyView = new DataView(body.buffer, body.byteOffset, body.byteLength);
+    if (kind === ROUTED_KIND_CAPABILITIES_REQUEST || kind === ROUTED_KIND_CAPABILITIES) {
+        if (body.byteLength < 4)
+            throw new Error('truncated transfer capability frame');
+        const length = bodyView.getUint32(0, false);
+        if (length > (kind === ROUTED_KIND_CAPABILITIES ? MAX_CAPABILITY_BYTES : maxHeaderBytes)
+            || body.byteLength !== 4 + length)
+            throw new Error('invalid transfer capability frame length');
+        if (kind === ROUTED_KIND_CAPABILITIES)
+            return { kind: 'capabilities', transferId,
+                capabilities: transferCapabilities(JSON.parse(new TextDecoder().decode(body.subarray(4)))) };
+        const header = length ? parseHeader(body.subarray(4), Number.MAX_SAFE_INTEGER) : undefined;
+        if (header && header.transferId !== transferId)
+            throw new Error('capability probe transferId mismatch');
+        return { kind: 'capabilities-request', transferId, header };
+    }
     if (kind === ROUTED_KIND_OFFER) {
         if (body.byteLength < 4)
             throw new Error('truncated routed offer');
@@ -222,11 +299,19 @@ export function decodeFrame(input, maxFileBytes = DEFAULT_MAX_BUFFERED_FILE_BYTE
             throw new Error('routed offer transferId mismatch');
         return { kind: 'offer', header };
     }
+    if (kind === ROUTED_KIND_WAITING) {
+        if (body.byteLength !== 12)
+            throw new Error('invalid receiver wait frame');
+        const offset = readU64(bodyView, 0), leaseMs = bodyView.getUint32(8, false);
+        if (offset > maxFileBytes || leaseMs < 1 || leaseMs > MAX_RECEIVER_WAIT_LEASE_MS)
+            throw new Error('invalid receiver wait lease or offset');
+        return { kind: 'waiting', transferId, offset, leaseMs };
+    }
     if ([ROUTED_KIND_RESUME, ROUTED_KIND_ACK, ROUTED_KIND_COMPLETE, ROUTED_KIND_COMPLETED].includes(kind)) {
         if (body.byteLength !== 8)
             throw new Error('invalid routed offset frame');
         const value = readU64(bodyView, 0);
-        if (value > maxFileBytes)
+        if (value > maxFileBytes && kind !== ROUTED_KIND_COMPLETED)
             throw new Error('routed transfer offset exceeds configured limit');
         if (kind === ROUTED_KIND_RESUME)
             return { kind: 'resume', transferId, offset: value };
@@ -351,15 +436,22 @@ function parseHeader(bytes, maxFileBytes) {
     if (value.sha256 !== undefined && !/^[a-f0-9]{64}$/i.test(value.sha256)) {
         throw new Error('invalid file transfer SHA-256 digest');
     }
+    requiredTransferCapabilities(value);
     return value;
 }
-async function sha256(blob) {
-    if (!globalThis.crypto?.subtle)
-        throw new Error('SHA-256 integrity requires Web Crypto');
-    const digest = await globalThis.crypto.subtle.digest('SHA-256', await blob.arrayBuffer());
-    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+async function sha256(blob, signal) {
+    const hash = incrementalSha256.create();
+    for (let offset = 0; offset < blob.size; offset += 64 * 1024) {
+        throwIfAborted(signal);
+        hash.update(new Uint8Array(await blob.slice(offset, offset + 64 * 1024).arrayBuffer()));
+    }
+    throwIfAborted(signal);
+    return Array.from(hash.digest(), byte => byte.toString(16).padStart(2, '0')).join('');
 }
 function bufferedSink(header, remoteNodeId) {
+    if (header.size > DEFAULT_MAX_BUFFERED_FILE_BYTES) {
+        throw new Error('buffered receive limit exceeded; install a streaming receive sink');
+    }
     const chunks = [];
     return {
         async write(chunk) { chunks.push(chunk.slice()); },
@@ -388,18 +480,28 @@ export function createTransfer(client, options = {}) {
         && (typeof adaptiveClient.getConnections === 'function' || !!adaptiveClient.diagnostics)) {
         return createRoutedTransfer(client, options);
     }
+    if (options.beforeReceiveBody)
+        throw new Error('transfer_capability_required: receiver pacing requires routed file transfer');
     const channel = options.channel ?? CHANNEL;
     const chunkBytes = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;
     const maxHeaderBytes = options.maxHeaderBytes ?? DEFAULT_MAX_HEADER_BYTES;
     const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_BUFFERED_FILE_BYTES;
     const ackTimeoutMs = options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS;
-    if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0)
-        throw new Error('chunkBytes must be positive');
+    if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > MAX_TRANSFER_CHUNK_BYTES)
+        throw new Error(`chunkBytes must be within 1..${MAX_TRANSFER_CHUNK_BYTES}`);
+    if (!Number.isSafeInteger(maxHeaderBytes) || maxHeaderBytes <= 0 || maxHeaderBytes > DEFAULT_MAX_HEADER_BYTES)
+        throw new Error(`maxHeaderBytes must be within 1..${DEFAULT_MAX_HEADER_BYTES}`);
     if (!Number.isSafeInteger(ackTimeoutMs) || ackTimeoutMs <= 0)
         throw new Error('ackTimeoutMs must be positive');
     client.channels.register(channel);
     return {
+        async sendAccepted(_deviceId, _source, _options = {}) {
+            throw new Error('transfer_capability_required: durable offer reconciliation requires routed file transfer');
+        },
         async send(deviceId, file, sendOptions = {}) {
+            if (sendOptions.requiredCapabilities || sendOptions.metadata?.['openrtc.required-capabilities.v1']
+                || file.size > LEGACY_MAX_FILE_BYTES)
+                throw new Error('transfer_capability_required: selected size/features require routed negotiation');
             if (file.size > maxFileBytes)
                 throw new Error(`file exceeds ${maxFileBytes} byte transfer limit`);
             throwIfAborted(sendOptions.signal);
@@ -432,6 +534,11 @@ export function createTransfer(client, options = {}) {
                 while (sent < file.size) {
                     throwIfAborted(sendOptions.signal);
                     const chunk = new Uint8Array(await file.slice(sent, sent + chunkBytes).arrayBuffer());
+                    await options.beforeSendBody?.({ transferId: id, peerId: deviceId,
+                        bytes: chunk.byteLength, offset: sent, signal: sendOptions.signal });
+                    await sendOptions.beforeSendBody?.({ transferId: id, peerId: deviceId,
+                        bytes: chunk.byteLength, offset: sent, signal: sendOptions.signal });
+                    throwIfAborted(sendOptions.signal);
                     await writer.write(chunk);
                     sent += chunk.byteLength;
                     sendOptions.onProgress?.({ transferId: id, transferredBytes: sent, totalBytes: file.size, direction: 'send' });
@@ -479,15 +586,36 @@ export function createTransfer(client, options = {}) {
                     const reader = new ByteReader(stream.readable);
                     const writer = stream.writable.getWriter();
                     let sink;
+                    const execution = new AbortController();
+                    const subscriptions = [];
+                    const watch = (signal) => {
+                        if (!signal)
+                            return;
+                        const abort = () => {
+                            execution.abort(signal.reason);
+                            void reader.cancel(signal.reason);
+                        };
+                        signal.addEventListener('abort', abort, { once: true });
+                        subscriptions.push(() => signal.removeEventListener('abort', abort));
+                        if (signal.aborted)
+                            abort();
+                    };
+                    watch(receiveOptions.signal);
                     try {
-                        const lengthBytes = await reader.exact(4, receiveOptions.signal);
+                        const lengthBytes = await reader.exact(4, execution.signal);
                         const headerLength = new DataView(lengthBytes.buffer, lengthBytes.byteOffset, 4).getUint32(0, false);
                         if (!headerLength || headerLength > maxHeaderBytes)
                             throw new Error(`invalid file transfer header length ${headerLength}`);
-                        const header = parseHeader(await reader.exact(headerLength, receiveOptions.signal), maxFileBytes);
+                        const header = parseHeader(await reader.exact(headerLength, execution.signal), maxFileBytes);
+                        if (requiredTransferCapabilities(header))
+                            throw new Error('transfer_capability_required: stream/v1 cannot negotiate required transfer features');
                         sink = options.createReceiveSink
                             ? await options.createReceiveSink(header, incoming.remoteNodeId)
                             : bufferedSink(header, incoming.remoteNodeId);
+                        if (sink.bodyPolicy?.requiresReceiverWait)
+                            throw new Error('transfer_capability_required: sink body policy requires routed file transfer');
+                        watch(sink.bodyPolicy?.signal);
+                        throwIfAborted(execution.signal);
                         const offset = header.offset ?? 0;
                         if (offset > 0 && sink.resumeOffset !== offset) {
                             throw new Error(`receive sink cannot resume at offset ${offset}`);
@@ -495,14 +623,20 @@ export function createTransfer(client, options = {}) {
                         let received = offset;
                         receiveOptions.onProgress?.({ transferId: header.transferId, transferredBytes: received, totalBytes: header.size, direction: 'receive' });
                         while (received < header.size) {
-                            throwIfAborted(receiveOptions.signal);
-                            const chunk = await reader.some(Math.min(chunkBytes, header.size - received), receiveOptions.signal);
+                            throwIfAborted(execution.signal);
+                            const chunk = await reader.some(Math.min(chunkBytes, header.size - received), execution.signal);
+                            throwIfAborted(execution.signal);
                             if (!chunk)
                                 throw new Error('file transfer stream ended before declared size');
+                            await sink.bodyPolicy?.beforeAttempt({ transferId: header.transferId,
+                                remoteNodeId: incoming.remoteNodeId, offset: received,
+                                bytes: chunk.byteLength, signal: execution.signal });
+                            throwIfAborted(execution.signal);
                             await sink.write(chunk);
                             received += chunk.byteLength;
                             receiveOptions.onProgress?.({ transferId: header.transferId, transferredBytes: received, totalBytes: header.size, direction: 'receive' });
                         }
+                        await sink.checkpoint?.();
                         const result = await sink.close();
                         if (header.sha256) {
                             const verified = sink.verifySha256
@@ -513,9 +647,13 @@ export function createTransfer(client, options = {}) {
                             if (!verified)
                                 throw new Error('file transfer integrity check failed');
                         }
+                        await receiveOptions.onFile({ header, remoteNodeId: incoming.remoteNodeId, result });
+                        throwIfAborted(execution.signal);
+                        await sink.commit?.();
+                        throwIfAborted(execution.signal);
                         await writer.write(new Uint8Array([ACK_OK]));
                         await writer.close();
-                        await receiveOptions.onFile({ header, remoteNodeId: incoming.remoteNodeId, result });
+                        writer.releaseLock();
                     }
                     catch (error) {
                         await sink?.abort(error).catch(() => undefined);
@@ -525,7 +663,13 @@ export function createTransfer(client, options = {}) {
                         // suppress local error reporting through backpressure.
                         void writer.write(new Uint8Array([ACK_REJECTED]))
                             .then(() => writer.close())
-                            .catch(() => writer.abort(error).catch(() => undefined));
+                            .catch(() => writer.abort(error).catch(() => undefined))
+                            .finally(() => writer.releaseLock());
+                    }
+                    finally {
+                        for (const unsubscribe of subscriptions)
+                            unsubscribe();
+                        await reader.cancel('file transfer stream consumed');
                     }
                 })();
                 return true;
@@ -550,20 +694,41 @@ export function createRoutedTransfer(client, options = {}) {
     const windowChunks = options.windowChunks ?? DEFAULT_ROUTED_WINDOW_CHUNKS;
     const maxRecoveryAttempts = options.maxRecoveryAttempts ?? 3;
     const channel = options.routing === 'segmented-stream' ? (options.channel ?? CHANNEL) : null;
+    const receiveWaitLeaseMs = options.receiveWaitLeaseMs ?? DEFAULT_RECEIVER_WAIT_LEASE_MS;
+    if (!Number.isSafeInteger(receiveWaitLeaseMs) || receiveWaitLeaseMs < 1 || receiveWaitLeaseMs > MAX_RECEIVER_WAIT_LEASE_MS)
+        throw new Error('receiveWaitLeaseMs must be within 1..60000');
     if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > DEFAULT_ROUTED_CHUNK_BYTES) {
         throw new Error(`routed chunkBytes must be within 1..${DEFAULT_ROUTED_CHUNK_BYTES}`);
     }
-    if (!Number.isSafeInteger(windowChunks) || windowChunks <= 0)
-        throw new Error('windowChunks must be positive');
-    if (!Number.isSafeInteger(maxRecoveryAttempts) || maxRecoveryAttempts < 0)
-        throw new Error('maxRecoveryAttempts must be non-negative');
+    if (!Number.isSafeInteger(maxHeaderBytes) || maxHeaderBytes <= 0 || maxHeaderBytes > DEFAULT_MAX_HEADER_BYTES)
+        throw new Error(`maxHeaderBytes must be within 1..${DEFAULT_MAX_HEADER_BYTES}`);
+    if (!Number.isSafeInteger(windowChunks) || windowChunks <= 0 || windowChunks > MAX_TRANSFER_WINDOW_CHUNKS)
+        throw new Error(`windowChunks must be within 1..${MAX_TRANSFER_WINDOW_CHUNKS}`);
+    if (!Number.isSafeInteger(maxRecoveryAttempts) || maxRecoveryAttempts < 0 || maxRecoveryAttempts > MAX_PROTOCOL_RECOVERY_ATTEMPTS)
+        throw new Error(`maxRecoveryAttempts must be within 0..${MAX_PROTOCOL_RECOVERY_ATTEMPTS}`);
+    if (!Number.isSafeInteger(ackTimeoutMs) || ackTimeoutMs <= 0)
+        throw new Error('ackTimeoutMs must be positive');
     if (channel)
         client.channels.register(channel);
     const incoming = new Map();
+    // Admission is asynchronous too: serialize offers before a sink exists.
+    const incomingWork = new Map();
     const completed = new Map();
     const controlListeners = new Map();
     let receiveOptions = null;
     let disposed = false;
+    const receiveClaims = requiredCapabilities({ durableResume: options.receiveCapabilities?.durableResume,
+        extensions: options.receiveCapabilities?.extensions });
+    if (receiveClaims.durableResume && !options.createReceiveSink)
+        throw new Error('transfer_capability_required: durable resume requires a product streaming sink');
+    const localCapabilities = (receiving) => ({
+        ...receiveClaims, receiveAvailable: receiving, durableResume: receiving && receiveClaims.durableResume,
+        extensions: receiving ? receiveClaims.extensions : [],
+        completionReceipt: typeof options.hasCompletionReceipt === 'function',
+        maxFileBytes: receiving ? (options.createReceiveSink ? maxFileBytes : Math.min(maxFileBytes, LEGACY_MAX_FILE_BYTES)) : 0,
+    });
+    const lifetime = new AbortController();
+    const activeWaits = new Set();
     const connectionMatches = (connection, id) => [connection.id, connection.remoteNodeId, connection.deviceId]
         .some((candidate) => typeof candidate === 'string' && candidate === id);
     const runtimeClient = client;
@@ -624,14 +789,50 @@ export function createRoutedTransfer(client, options = {}) {
         const connection = typeof target === 'string' ? await resolveConnection(target) : target;
         await connection.send(encodeFrame(frame, maxHeaderBytes, chunkBytes));
     };
-    const waitForControl = async (transferId, predicate, send, signal, expectedPeer) => {
-        const identity = channel && expectedPeer ? await client.peers?.identity?.(expectedPeer) : null;
+    const waitForControl = async (transferId, predicate, send, signal, expectedPeer, waiting) => {
+        throwIfAborted(signal);
+        throwIfAborted(lifetime.signal);
+        const identity = expectedPeer ? await client.peers?.identity?.(expectedPeer) : null;
         const expectedNode = identity?.nodeId ?? expectedPeer;
-        let resolveFrame;
-        const operation = new Promise((resolve) => { resolveFrame = resolve; });
+        throwIfAborted(signal);
+        throwIfAborted(lifetime.signal);
+        let resolveFrame, rejectFrame;
+        let settled = false, started = false, waitUntil = 0;
+        let timer;
+        const operation = new Promise((resolve, reject) => {
+            resolveFrame = frame => { if (!settled) {
+                settled = true;
+                resolve(frame);
+            } };
+            rejectFrame = error => { if (!settled) {
+                settled = true;
+                reject(error);
+            } };
+        });
+        // A cancellation can arrive while local policy/backpressure is still
+        // being awaited. Observe the verdict immediately without starting its
+        // remote-ACK deadline before body submission finishes.
+        void operation.catch(() => undefined);
+        const arm = () => {
+            if (settled || !started)
+                return;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = setTimeout(() => rejectFrame(new Error(`file transfer acknowledgement timed out after ${ackTimeoutMs}ms`)), Math.max(ackTimeoutMs, waitUntil - performance.now()));
+        };
+        const onAbort = () => rejectFrame(signal?.aborted ? signal.reason : lifetime.signal.reason);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        lifetime.signal.addEventListener('abort', onAbort, { once: true });
         const listener = (frame, peerId) => {
-            if (channel && peerId !== expectedNode)
+            if (expectedNode && peerId !== expectedNode)
                 return;
+            if (frame.kind === 'waiting') {
+                if (waiting && frame.offset >= waiting.minimumOffset && frame.offset <= waiting.maximumOffset) {
+                    waitUntil = performance.now() + frame.leaseMs;
+                    arm();
+                }
+                return; // Waiting never acknowledges bytes or completion.
+            }
             if (predicate(frame))
                 resolveFrame(frame);
         };
@@ -644,22 +845,26 @@ export function createRoutedTransfer(client, options = {}) {
                 await send();
             }
             catch (error) {
-                // A replaceable route can close after accepting the frame but
-                // before its local delivery acknowledgement settles. Keep the
-                // protocol listener alive for the bounded peer-ACK window: the
-                // receiver may already be replying on the replacement route.
+                if (error instanceof TransferBodyAdmissionFailure || signal?.aborted || lifetime.signal.aborted)
+                    throw error;
                 sendError = error;
             }
+            started = true;
+            arm();
             try {
-                return await waitWithDeadline(operation, ackTimeoutMs, signal);
+                return await operation;
             }
             catch (error) {
-                if (signal?.aborted)
+                if (signal?.aborted || lifetime.signal.aborted)
                     throw error;
                 throw sendError ?? error;
             }
         }
         finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            lifetime.signal.removeEventListener('abort', onAbort);
             listeners.delete(listener);
             if (!listeners.size)
                 controlListeners.delete(transferId);
@@ -673,11 +878,80 @@ export function createRoutedTransfer(client, options = {}) {
             receiveOptions?.onError?.(error instanceof Error ? error : new Error(String(error)));
         }
     };
+    const receiveWork = async (state, configured, work) => {
+        if (state.sink && !options.beforeReceiveBody && !state.sink.bodyPolicy)
+            return work(configured.signal ?? lifetime.signal);
+        const controller = new AbortController();
+        const parents = [configured.signal, lifetime.signal, state.sink?.bodyPolicy?.signal].filter((signal) => !!signal);
+        const onAbort = () => controller.abort(parents.find(signal => signal.aborted)?.reason);
+        const negotiated = supportsReceiverWait(state.header);
+        const active = { owner: configured, cancel: () => controller.abort(new Error('execution_suspended: receive execution retired')) };
+        activeWaits.add(active);
+        let timer;
+        const pulse = async () => {
+            throwIfAborted(controller.signal);
+            if (!negotiated)
+                return;
+            await sendFrame(state.connection, { kind: 'waiting', transferId: state.header.transferId,
+                offset: state.confirmed, leaseMs: receiveWaitLeaseMs });
+            throwIfAborted(controller.signal);
+        };
+        const renew = async () => {
+            try {
+                await pulse();
+                timer = setTimeout(() => { void renew(); }, Math.max(1, Math.floor(receiveWaitLeaseMs / 3)));
+            }
+            catch (error) {
+                controller.abort(error);
+            }
+        };
+        let rejectAbort;
+        const aborted = new Promise((_, reject) => { rejectAbort = reject; });
+        void aborted.catch(() => undefined);
+        const onLocalAbort = () => rejectAbort(controller.signal.reason);
+        controller.signal.addEventListener('abort', onLocalAbort, { once: true });
+        for (const signal of parents)
+            signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            if (parents.some(signal => signal.aborted))
+                onAbort();
+            throwIfAborted(controller.signal);
+            await pulse();
+            if (negotiated)
+                timer = setTimeout(() => { void renew(); }, Math.max(1, Math.floor(receiveWaitLeaseMs / 3)));
+            const result = await Promise.race([work(controller.signal), aborted]);
+            throwIfAborted(controller.signal);
+            return result;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            controller.abort(new Error('Receive policy wait ended'));
+            controller.signal.removeEventListener('abort', onLocalAbort);
+            for (const signal of parents)
+                signal.removeEventListener('abort', onAbort);
+            activeWaits.delete(active);
+        }
+    };
     const processIncoming = async (connection, remoteNodeId, frame) => {
         const configured = receiveOptions;
+        const key = JSON.stringify([remoteNodeId, routedTransferId(frame)]);
+        if (frame.kind === 'capabilities-request') {
+            if (frame.header) {
+                const retained = completed.get(key);
+                if (retained && retained.header !== JSON.stringify(frame.header))
+                    throw new Error('transfer_identity_conflict: capability probe differs from completed offer');
+                if (retained || await options.hasCompletionReceipt?.(frame.header, remoteNodeId)) {
+                    await respond(connection, { kind: 'completed', transferId: frame.transferId, size: frame.header.size });
+                    return;
+                }
+            }
+            await respond(connection, { kind: 'capabilities', transferId: frame.transferId,
+                capabilities: localCapabilities(Boolean(configured) && !configured?.signal?.aborted) });
+            return;
+        }
         if (!configured)
             return;
-        const key = JSON.stringify([remoteNodeId, routedTransferId(frame)]);
         if (frame.kind === 'offer') {
             const alreadyCompleted = completed.get(key);
             if (alreadyCompleted) {
@@ -690,25 +964,81 @@ export function createRoutedTransfer(client, options = {}) {
             if (existing) {
                 if (JSON.stringify(existing.header) !== JSON.stringify(frame.header))
                     throw new Error('transfer ID reused with a different header');
+                await existing.sink.checkpoint?.();
+                existing.confirmed = existing.received;
                 await respond(connection, { kind: 'resume', transferId: frame.header.transferId, offset: existing.received });
                 return;
             }
             try {
-                const sink = options.createReceiveSink
-                    ? await options.createReceiveSink(frame.header, remoteNodeId)
-                    : bufferedSink(frame.header, remoteNodeId);
-                const received = sink.resumeOffset ?? 0;
-                if (!Number.isSafeInteger(received) || received < 0 || received > frame.header.size) {
-                    throw new Error('receive sink returned an invalid resumeOffset');
+                if (await options.hasCompletionReceipt?.(frame.header, remoteNodeId)) {
+                    completed.set(key, { size: frame.header.size, header: JSON.stringify(frame.header) });
+                    if (completed.size > 1024)
+                        completed.delete(completed.keys().next().value);
+                    await respond(connection, { kind: 'completed', transferId: frame.header.transferId, size: frame.header.size });
+                    return;
+                }
+                requireCapabilities(localCapabilities(true), frame.header);
+                if (options.beforeReceiveBody && !supportsReceiverWait(frame.header))
+                    throw new Error('transfer_capability_required: receiver pacing requires negotiated wait support');
+                throwIfAborted(configured.signal);
+                const sink = await receiveWork({ header: frame.header, connection, confirmed: 0 }, configured, async (signal) => {
+                    const opened = options.createReceiveSink
+                        ? await options.createReceiveSink(frame.header, remoteNodeId, signal)
+                        : bufferedSink(frame.header, remoteNodeId);
+                    if (signal.aborted) {
+                        await opened.abort(signal.reason);
+                        throw signal.reason;
+                    }
+                    return opened;
+                });
+                let received;
+                try {
+                    throwIfAborted(configured.signal);
+                    throwIfAborted(lifetime.signal);
+                    if (receiveOptions !== configured)
+                        throw new Error('execution_suspended: receive execution retired');
+                    throwIfAborted(sink.bodyPolicy?.signal);
+                    if (sink.bodyPolicy?.requiresReceiverWait && !supportsReceiverWait(frame.header))
+                        throw new Error('transfer_capability_required: receiver pacing requires negotiated wait support');
+                    if (receiveClaims.durableResume && !sink.checkpoint)
+                        throw new Error('transfer_capability_required: durable resume requires a checkpointing sink');
+                    received = sink.resumeOffset ?? 0;
+                    if (!Number.isSafeInteger(received) || received < 0 || received > frame.header.size)
+                        throw new Error('receive sink returned an invalid resumeOffset');
+                }
+                catch (error) {
+                    await sink.abort(error instanceof Error ? error : new Error(String(error)));
+                    throw error;
                 }
-                incoming.set(key, {
+                const state = {
                     header: frame.header,
                     remoteNodeId,
                     connection,
                     sink,
                     received,
-                    chain: Promise.resolve(),
-                });
+                    confirmed: received,
+                };
+                incoming.set(key, state);
+                const policySignal = sink.bodyPolicy?.signal;
+                if (policySignal) {
+                    const retire = () => {
+                        // Active work observes the same signal; serialize cleanup
+                        // behind it so no sink operation races its own abort.
+                        void (incomingWork.get(key) ?? Promise.resolve()).finally(async () => {
+                            if (incoming.get(key) !== state)
+                                return;
+                            incoming.delete(key);
+                            state.detachPolicy?.();
+                            await sink.abort(policySignal.reason).catch(() => undefined);
+                            await respond(state.connection, { kind: 'reject', transferId: state.header.transferId,
+                                reason: 'execution_suspended: receive execution retired' });
+                        }).catch(() => undefined);
+                    };
+                    policySignal.addEventListener('abort', retire, { once: true });
+                    state.detachPolicy = () => policySignal.removeEventListener('abort', retire);
+                    if (policySignal.aborted)
+                        retire();
+                }
                 configured.onProgress?.({ transferId: frame.header.transferId, transferredBytes: received, totalBytes: frame.header.size, direction: 'receive' });
                 await respond(connection, { kind: 'resume', transferId: frame.header.transferId, offset: received });
             }
@@ -730,39 +1060,76 @@ export function createRoutedTransfer(client, options = {}) {
         }
         state.connection = connection;
         if (frame.kind === 'chunk') {
-            if (frame.offset < state.received && frame.offset + frame.bytes.byteLength <= state.received) {
-                if (frame.ackRequested)
+            await receiveWork(state, configured, async (signal) => {
+                // Policy accounts every admitted body attempt, including a
+                // retransmitted prefix. Deduplication changes logical progress,
+                // never the actual payload already submitted by the peer.
+                await options.beforeReceiveBody?.({ transferId: frame.transferId, remoteNodeId,
+                    offset: frame.offset, bytes: frame.bytes.byteLength, signal });
+                await state.sink.bodyPolicy?.beforeAttempt({ transferId: frame.transferId, remoteNodeId,
+                    offset: frame.offset, bytes: frame.bytes.byteLength, signal });
+                throwIfAborted(signal);
+                if (frame.offset < state.received && frame.offset + frame.bytes.byteLength <= state.received) {
+                    if (frame.ackRequested) {
+                        await state.sink.checkpoint?.();
+                        throwIfAborted(signal);
+                        state.confirmed = state.received;
+                        await respond(connection, { kind: 'ack', transferId: frame.transferId, offset: state.received });
+                    }
+                    return;
+                }
+                if (frame.offset !== state.received || state.received + frame.bytes.byteLength > state.header.size) {
+                    await state.sink.checkpoint?.();
+                    throwIfAborted(signal);
+                    state.confirmed = state.received;
                     await respond(connection, { kind: 'ack', transferId: frame.transferId, offset: state.received });
-                return;
-            }
-            if (frame.offset !== state.received || state.received + frame.bytes.byteLength > state.header.size) {
-                await respond(connection, { kind: 'ack', transferId: frame.transferId, offset: state.received });
-                return;
-            }
-            await state.sink.write(frame.bytes);
-            state.received += frame.bytes.byteLength;
-            configured.onProgress?.({ transferId: frame.transferId, transferredBytes: state.received, totalBytes: state.header.size, direction: 'receive' });
-            if (frame.ackRequested)
-                await respond(connection, { kind: 'ack', transferId: frame.transferId, offset: state.received });
+                    return;
+                }
+                await state.sink.write(frame.bytes);
+                throwIfAborted(signal);
+                state.received += frame.bytes.byteLength;
+                configured.onProgress?.({ transferId: frame.transferId, transferredBytes: state.received, totalBytes: state.header.size, direction: 'receive' });
+                if (frame.ackRequested) {
+                    await state.sink.checkpoint?.();
+                    throwIfAborted(signal);
+                    state.confirmed = state.received;
+                    await respond(connection, { kind: 'ack', transferId: frame.transferId, offset: state.received });
+                }
+            });
             return;
         }
         if (frame.kind === 'complete') {
             if (frame.size !== state.header.size || state.received !== state.header.size) {
+                await state.sink.checkpoint?.();
+                state.confirmed = state.received;
                 await respond(connection, { kind: 'ack', transferId: frame.transferId, offset: state.received });
                 return;
             }
-            const result = await state.sink.close();
-            if (state.header.sha256) {
-                const verified = state.sink.verifySha256
-                    ? await state.sink.verifySha256(state.header.sha256)
-                    : result && typeof result === 'object' && 'blob' in result
-                        ? await sha256(result.blob) === state.header.sha256.toLowerCase()
-                        : false;
-                if (!verified)
-                    throw new Error('file transfer integrity check failed');
-            }
-            await configured.onFile({ header: state.header, remoteNodeId: state.remoteNodeId, result });
+            await receiveWork(state, configured, async (signal) => {
+                await state.sink.checkpoint?.();
+                state.confirmed = state.received;
+                throwIfAborted(signal);
+                const result = await state.sink.close();
+                if (state.header.sha256) {
+                    const verified = state.sink.verifySha256
+                        ? await state.sink.verifySha256(state.header.sha256)
+                        : result && typeof result === 'object' && 'blob' in result
+                            ? await sha256(result.blob) === state.header.sha256.toLowerCase()
+                            : false;
+                    if (!verified)
+                        throw new Error('file transfer integrity check failed');
+                }
+                throwIfAborted(signal);
+                await configured.onFile({ header: state.header, remoteNodeId: state.remoteNodeId, result });
+                throwIfAborted(signal);
+                await state.sink.commit?.();
+                if (requiredTransferCapabilities(state.header)?.completionReceipt
+                    && !await options.hasCompletionReceipt?.(state.header, state.remoteNodeId))
+                    throw new Error('transfer_capability_required: receiver did not persist the required completion receipt');
+                throwIfAborted(signal);
+            });
             incoming.delete(key);
+            state.detachPolicy?.();
             completed.set(key, { size: frame.size, header: JSON.stringify(state.header) });
             if (completed.size > 1024)
                 completed.delete(completed.keys().next().value);
@@ -800,28 +1167,30 @@ export function createRoutedTransfer(client, options = {}) {
             remoteNodeId: connection.remoteNodeId ?? null,
             controlListenerCount: listeners?.size ?? 0,
         });
-        if (listeners && ['resume', 'ack', 'completed', 'reject'].includes(frame.kind)) {
+        if (listeners && ['resume', 'ack', 'waiting', 'completed', 'reject', 'capabilities'].includes(frame.kind)) {
             for (const listener of [...listeners])
                 listener(frame, connection.remoteNodeId ?? connection.deviceId ?? connection.id ?? 'unknown');
         }
-        if (['resume', 'ack', 'completed', 'reject'].includes(frame.kind))
+        if (['resume', 'ack', 'waiting', 'completed', 'reject', 'capabilities'].includes(frame.kind))
             return;
         const routeConnection = connection;
         const remoteNodeId = routeConnection.remoteNodeId ?? routeConnection.deviceId ?? routeConnection.id ?? 'unknown';
         const key = JSON.stringify([remoteNodeId, frameId]);
-        const current = incoming.get(key);
-        const chain = (current?.chain ?? Promise.resolve())
-            .then(() => processIncoming(routeConnection, remoteNodeId, frame))
+        const chain = (incomingWork.get(key) ?? Promise.resolve())
+            .then(() => { if (!disposed)
+            return processIncoming(routeConnection, remoteNodeId, frame); })
             .catch(async (error) => {
             const state = incoming.get(key);
             incoming.delete(key);
+            state?.detachPolicy?.();
             await state?.sink.abort(error).catch(() => undefined);
             receiveOptions?.onError?.(error instanceof Error ? error : new Error(String(error)));
             await respond(routeConnection, { kind: 'reject', transferId: routedTransferId(frame), reason: String(error) });
         });
-        if (current)
-            current.chain = chain;
-        void chain;
+        incomingWork.set(key, chain);
+        const retireWork = () => { if (incomingWork.get(key) === chain)
+            incomingWork.delete(key); };
+        void chain.then(retireWork, retireWork);
     };
     const messageSource = client;
     let offMessage;
@@ -837,7 +1206,7 @@ export function createRoutedTransfer(client, options = {}) {
                 try {
                     const prefix = await waitWithDeadline(reader.exact(4), ackTimeoutMs);
                     const size = new DataView(prefix.buffer, prefix.byteOffset, 4).getUint32(0, false);
-                    const limit = Math.max(maxHeaderBytes + 4, chunkBytes + 9) + MAX_ROUTED_TRANSFER_ID_BYTES + 7;
+                    const limit = Math.max(maxHeaderBytes + 4, MAX_CAPABILITY_BYTES + 4, chunkBytes + 9) + MAX_ROUTED_TRANSFER_ID_BYTES + 7;
                     if (!size || size > limit)
                         throw new Error('invalid file transfer segment length');
                     const bytes = await waitWithDeadline(reader.exact(size), ackTimeoutMs);
@@ -872,106 +1241,191 @@ export function createRoutedTransfer(client, options = {}) {
             attach(connection);
         offMessage = client.diagnostics.onConnection((connection) => attach(connection));
     }
-    return {
-        async send(deviceId, file, sendOptions = {}) {
-            if (disposed)
-                throw new Error('routed file-transfer protocol is disposed');
-            if (file.size > maxFileBytes)
-                throw new Error(`file exceeds ${maxFileBytes} byte transfer limit`);
+    const sendOffered = async (deviceId, proposed, openSource, sendOptions, verifySource) => {
+        if (disposed)
+            throw new Error('routed file-transfer protocol is disposed');
+        throwIfAborted(sendOptions.signal);
+        const encoded = encodeHeader(proposed, maxHeaderBytes);
+        const header = parseHeader(encoded.subarray(4), verifySource ? Number.MAX_SAFE_INTEGER : maxFileBytes);
+        if (header.offset !== undefined)
+            throw new Error('routed immutable offers cannot contain a sender resume offset');
+        if (verifySource && !header.sha256)
+            throw new Error('accepted file transfer requires an immutable SHA-256 revision');
+        const id = header.transferId;
+        let opened;
+        const sourceFile = () => opened ?? (opened = (async () => {
             throwIfAborted(sendOptions.signal);
-            const id = sendOptions.transferId ?? transferId();
-            const header = {
-                version: 1,
-                transferId: id,
-                name: file.name,
-                size: file.size,
-                mimeType: file.type || 'application/octet-stream',
-                metadata: sendOptions.metadata,
-                sha256: sendOptions.integrity === 'sha256' ? await sha256(file) : undefined,
-            };
-            let recoveryAttempts = 0;
-            const recover = async (operation) => {
-                for (let attempt = 0;; attempt += 1) {
-                    throwIfAborted(sendOptions.signal);
-                    try {
-                        return await operation();
-                    }
-                    catch (error) {
-                        if (sendOptions.signal?.aborted || error instanceof TransferRejectedError || attempt >= maxRecoveryAttempts)
-                            throw error;
-                    }
-                }
-            };
-            const offer = async () => {
-                const response = await waitForControl(id, (frame) => frame.kind === 'resume' || frame.kind === 'completed' || frame.kind === 'reject', () => sendFrame(deviceId, { kind: 'offer', header }), sendOptions.signal, deviceId);
-                if (response.kind === 'reject')
-                    throw new TransferRejectedError(`file transfer rejected: ${response.reason}`);
-                if (response.kind === 'completed')
-                    return response.size;
-                if (response.kind !== 'resume' || response.offset > file.size)
-                    throw new Error('invalid file transfer resume response');
-                return response.offset;
-            };
-            let confirmed = await recover(offer);
-            sendOptions.onProgress?.({ transferId: id, transferredBytes: confirmed, totalBytes: file.size, direction: 'send' });
-            while (confirmed < file.size) {
+            const file = await openSource();
+            if (file.size !== header.size || file.name !== header.name
+                || (file.type || 'application/octet-stream') !== header.mimeType)
+                throw new Error('transfer_identity_conflict: source differs from the accepted offer');
+            if (verifySource && await sha256(file, sendOptions.signal) !== header.sha256.toLowerCase())
+                throw new Error('transfer_identity_conflict: source revision differs from the accepted offer');
+            throwIfAborted(sendOptions.signal);
+            return file;
+        })());
+        let receiptConfirmed = false;
+        let recoveryAttempts = 0;
+        const recover = async (operation) => {
+            for (let attempt = 0;; attempt += 1) {
                 throwIfAborted(sendOptions.signal);
-                const windowStart = confirmed;
-                let cursor = confirmed;
-                const frames = [];
-                for (let index = 0; index < windowChunks && cursor < file.size; index += 1) {
-                    const bytes = new Uint8Array(await file.slice(cursor, cursor + chunkBytes).arrayBuffer());
-                    const end = cursor + bytes.byteLength;
-                    frames.push({ kind: 'chunk', transferId: id, offset: cursor, ackRequested: end === file.size || index === windowChunks - 1, bytes });
-                    cursor = end;
-                }
                 try {
-                    const response = await waitForControl(id, (frame) => (frame.kind === 'ack' && frame.offset >= windowStart) || frame.kind === 'reject', async () => {
-                        for (const frame of frames)
-                            await sendFrame(deviceId, frame);
-                    }, sendOptions.signal, deviceId);
-                    if (response.kind === 'reject')
-                        throw new TransferRejectedError(`file transfer rejected: ${response.reason}`);
-                    if (response.kind !== 'ack' || response.offset < windowStart || response.offset > cursor) {
-                        throw new Error('invalid file transfer offset acknowledgement');
-                    }
-                    confirmed = response.offset;
-                    recoveryAttempts = 0;
-                    sendOptions.onProgress?.({ transferId: id, transferredBytes: confirmed, totalBytes: file.size, direction: 'send' });
+                    return await operation();
                 }
                 catch (error) {
-                    if (sendOptions.signal?.aborted || error instanceof TransferRejectedError)
+                    if (sendOptions.signal?.aborted || error instanceof TransferRejectedError || attempt >= maxRecoveryAttempts)
                         throw error;
-                    if (recoveryAttempts >= maxRecoveryAttempts)
+                }
+            }
+        };
+        const offer = async () => {
+            if (header.size > LEGACY_MAX_FILE_BYTES || header.size > maxFileBytes || requiredTransferCapabilities(header)) {
+                let verdict;
+                try {
+                    verdict = await waitForControl(id, frame => frame.kind === 'capabilities' || frame.kind === 'reject'
+                        || frame.kind === 'completed' && frame.size === header.size, () => sendFrame(deviceId, { kind: 'capabilities-request', transferId: id, header }), sendOptions.signal, deviceId);
+                }
+                catch (error) {
+                    if (sendOptions.signal?.aborted || lifetime.signal.aborted)
                         throw error;
-                    recoveryAttempts += 1;
-                    confirmed = await recover(offer);
+                    throw new Error('transfer_capability_required: receiver capability response unavailable; upgrade the receiving client or retry when it can receive');
+                }
+                if (verdict.kind === 'completed') {
+                    receiptConfirmed = true;
+                    return header.size;
+                }
+                if (verdict.kind === 'reject')
+                    throw new TransferRejectedError(verdict.reason);
+                if (verdict.kind !== 'capabilities')
+                    throw new TransferRejectedError('transfer_capability_required: invalid receiver capability response');
+                try {
+                    requireCapabilities(verdict.capabilities, header);
+                }
+                catch (error) {
+                    throw new TransferRejectedError(error.message);
+                }
+            }
+            if (header.size > maxFileBytes)
+                throw new TransferRejectedError(`file exceeds ${maxFileBytes} byte transfer limit`);
+            const response = await waitForControl(id, (frame) => frame.kind === 'resume' || frame.kind === 'completed' || frame.kind === 'reject', () => sendFrame(deviceId, { kind: 'offer', header }), sendOptions.signal, deviceId, supportsReceiverWait(header) ? { minimumOffset: 0, maximumOffset: 0 } : undefined);
+            if (response.kind === 'reject')
+                throw new TransferRejectedError(`file transfer rejected: ${response.reason}`);
+            if (response.kind === 'completed') {
+                if (response.size !== header.size)
+                    throw new Error('invalid completed file transfer size');
+                receiptConfirmed = true;
+                return response.size;
+            }
+            if (response.kind !== 'resume' || response.offset > header.size)
+                throw new Error('invalid file transfer resume response');
+            return response.offset;
+        };
+        let confirmed = await recover(offer);
+        sendOptions.onProgress?.({ transferId: id, transferredBytes: confirmed, totalBytes: header.size, direction: 'send' });
+        while (confirmed < header.size) {
+            const file = await sourceFile();
+            throwIfAborted(sendOptions.signal);
+            const windowStart = confirmed;
+            let cursor = confirmed;
+            const frames = [];
+            for (let index = 0; index < windowChunks && cursor < header.size; index += 1) {
+                const bytes = new Uint8Array(await file.slice(cursor, cursor + chunkBytes).arrayBuffer());
+                const end = cursor + bytes.byteLength;
+                frames.push({ kind: 'chunk', transferId: id, offset: cursor, ackRequested: end === header.size || index === windowChunks - 1, bytes });
+                cursor = end;
+            }
+            try {
+                const response = await waitForControl(id, (frame) => (frame.kind === 'ack' && frame.offset >= windowStart) || frame.kind === 'reject', async () => {
+                    for (const frame of frames) {
+                        if (frame.kind === 'chunk') {
+                            try {
+                                await options.beforeSendBody?.({ transferId: id, peerId: deviceId,
+                                    bytes: frame.bytes.byteLength, offset: frame.offset, signal: sendOptions.signal });
+                                await sendOptions.beforeSendBody?.({ transferId: id, peerId: deviceId,
+                                    bytes: frame.bytes.byteLength, offset: frame.offset, signal: sendOptions.signal });
+                            }
+                            catch (error) {
+                                throw new TransferBodyAdmissionFailure(error);
+                            }
+                            throwIfAborted(sendOptions.signal);
+                        }
+                        await sendFrame(deviceId, frame);
+                    }
+                }, sendOptions.signal, deviceId, supportsReceiverWait(header) ? { minimumOffset: windowStart, maximumOffset: cursor } : undefined);
+                if (response.kind === 'reject')
+                    throw new TransferRejectedError(`file transfer rejected: ${response.reason}`);
+                if (response.kind !== 'ack' || response.offset < windowStart || response.offset > cursor) {
+                    throw new Error('invalid file transfer offset acknowledgement');
                 }
+                confirmed = response.offset;
+                recoveryAttempts = 0;
+                sendOptions.onProgress?.({ transferId: id, transferredBytes: confirmed, totalBytes: header.size, direction: 'send' });
             }
-            const completion = await recover(() => waitForControl(id, (frame) => frame.kind === 'completed' || frame.kind === 'ack' || frame.kind === 'reject', () => sendFrame(deviceId, { kind: 'complete', transferId: id, size: file.size }), sendOptions.signal, deviceId));
-            if (completion.kind === 'reject')
-                throw new TransferRejectedError(`file transfer rejected: ${completion.reason}`);
-            if (completion.kind !== 'completed' || completion.size !== file.size) {
-                throw new Error('receiver did not confirm completed file transfer');
+            catch (error) {
+                if (error instanceof TransferBodyAdmissionFailure)
+                    throw error.failure;
+                if (sendOptions.signal?.aborted || error instanceof TransferRejectedError)
+                    throw error;
+                if (recoveryAttempts >= maxRecoveryAttempts)
+                    throw error;
+                recoveryAttempts += 1;
+                confirmed = await recover(offer);
             }
+        }
+        if (receiptConfirmed)
             return id;
+        const completion = await recover(() => waitForControl(id, (frame) => frame.kind === 'completed' || frame.kind === 'ack' || frame.kind === 'reject', () => sendFrame(deviceId, { kind: 'complete', transferId: id, size: header.size }), sendOptions.signal, deviceId, supportsReceiverWait(header) ? { minimumOffset: header.size, maximumOffset: header.size } : undefined));
+        if (completion.kind === 'reject')
+            throw new TransferRejectedError(`file transfer rejected: ${completion.reason}`);
+        if (completion.kind !== 'completed' || completion.size !== header.size) {
+            throw new Error('receiver did not confirm completed file transfer');
+        }
+        return id;
+    };
+    return {
+        async sendAccepted(deviceId, source, sendOptions = {}) {
+            return sendOffered(deviceId, source.header, () => source.openSource(), sendOptions, true);
+        },
+        async send(deviceId, file, sendOptions = {}) {
+            if (file.size > maxFileBytes)
+                throw new Error(`file exceeds ${maxFileBytes} byte transfer limit`);
+            throwIfAborted(sendOptions.signal);
+            const proposed = withReceiverWaitCapability({
+                version: 1, transferId: sendOptions.transferId ?? transferId(), name: file.name,
+                size: file.size, mimeType: file.type || 'application/octet-stream',
+                metadata: sendOptions.metadata,
+                sha256: sendOptions.integrity === 'sha256' ? await sha256(file, sendOptions.signal) : undefined,
+            });
+            const header = sendOptions.requiredCapabilities
+                ? withRequiredCapabilities(proposed, sendOptions.requiredCapabilities) : proposed;
+            return sendOffered(deviceId, header, async () => file, sendOptions, false);
         },
         onIncoming(configured) {
+            if (receiveOptions !== configured)
+                for (const wait of activeWaits)
+                    if (wait.owner === receiveOptions)
+                        wait.cancel();
             receiveOptions = configured;
             return () => {
                 if (receiveOptions === configured)
                     receiveOptions = null;
+                for (const wait of activeWaits)
+                    if (wait.owner === configured)
+                        wait.cancel();
             };
         },
         dispose() {
             disposed = true;
+            lifetime.abort(new Error('file-transfer protocol disposed'));
             offMessage();
             if (channel)
                 client.channels.unregister(channel.id);
             receiveOptions = null;
             controlListeners.clear();
-            for (const state of incoming.values())
+            for (const state of incoming.values()) {
+                state.detachPolicy?.();
                 void state.sink.abort(new Error('file-transfer protocol disposed'));
+            }
             incoming.clear();
         },
     };