openrtc-file-transfer 2.9.7 → 2.9.8

package/README.md

@@ -53,3 +53,121 @@ constructs a hidden client or activates a second avenue. It also never caches a
 transport, dials a peer, or promotes a route. The
 consumer keeps durable product intent pending until the receiver confirms the
 completed size and integrity.
+
+### Durable accepted sources
+
+The routed `sendAccepted(deviceId, { header, openSource }, options)` source API
+accepts the product's persisted immutable header, including SHA-256. It first
+reconciles the offer with the authenticated receiver. A committed completion
+receipt returns without opening the local file; otherwise missing bytes cause
+one lazy source open and bounded, abort-aware revision verification before body
+transmission. The product owns source storage, authorization, queue state and
+receipt persistence. No connection or additional protocol handler is created.
+The legacy stream implementation rejects this API before sending bytes. Consumers
+of older published packages must detect API availability and retain their prior
+source-first path until qualified artifacts are adopted.
+
+### Receive pacing and deadline renewal
+
+Routed message and segmented-stream receivers may use `beforeReceiveBody` to
+admit each authenticated body attempt into a product rate/quota controller.
+It receives transfer ID, remote node ID, offset, byte count and an abort signal.
+Duplicate body attempts consume policy bytes without advancing logical progress
+or writing the same prefix twice. Control frames bypass body policy. Payload
+attempts are application bytes, not an exact physical-network counter.
+
+Receiver pacing requires the immutable offer metadata
+`openrtc.receive-wait: "1"`. Fresh routed `send` offers advertise this capability;
+call `withReceiverWaitCapability(header)` **before** persisting a new accepted
+offer. `sendAccepted` preserves that exact persisted header, including metadata.
+A paced receiver rejects a legacy offer before allocating its sink or reading
+source bytes. A product-confirmed completion receipt still returns body-free,
+without running a body policy or requiring the legacy source to exist.
+
+`BULK_RECEIVE_FLOW_CONTROL_VERSION === 1` also supports per-sink `bodyPolicy`.
+Use its captured execution `signal`, `beforeAttempt` callback and
+`requiresReceiverWait` admission flag when product storage owns each job's
+policy/lease. The runtime callback still runs first; a sink cannot bypass it.
+A sink with `requiresReceiverWait: false` admits old offers without sending
+unsupported wait controls. Its callback must remain unpaced for such an offer
+or reject if a later policy requires waiting. Required waits reject before body
+acceptance and abort any prepared sink. Product receipts are checked first.
+Signal retirement aborts active policy work and releases idle receive sinks.
+Stream/v1 cannot host this body policy and rejects it before reading body data.
+
+OFT2 kind `0x08` is a waiting control frame: transfer ID, big-endian u64 last
+checkpointed offset and big-endian u32 lease milliseconds (1–60,000). The
+receiver renews its configurable lease (default 10,000 ms) during body policy,
+sink IO/checkpointing and final verification/publication. The sender accepts
+renewal only from the expected authenticated peer, for the active transfer,
+within its current body window and only when the offer negotiated support.
+Waiting neither ACKs bytes nor confirms delivery. If renewal stops, the current
+lease expires and the normal bounded recovery applies. Application expiry and
+execution permission remain the product's responsibility.
+
+Caller cancellation, receiver subscription stop/replacement and protocol
+disposal abort active policy work and stop renewal. Hooks must honor the abort
+signal; durable sinks must retain their product execution/commit fences. A sink
+that finishes creation after execution retirement is aborted rather than
+accepted. Legacy raw-stream framing rejects receive pacing; native consumers
+must qualify and implement the same negotiated deadline behavior before
+advertising the capability. Neither waiting nor body policy changes OpenRTC's
+connection, admission or route ownership.
+
+### Required capabilities and large-file admission
+
+For routed message or segmented-stream transfers, `send` accepts
+`requiredCapabilities: { durableResume?, completionReceipt?, extensions? }`.
+Accepted jobs instead call `withRequiredCapabilities(header, requirements)` before
+persisting their immutable header; `sendAccepted` preserves that exact metadata.
+A requirement is encoded under `openrtc.required-capabilities.v1` as a closed
+version-1 JSON document. Unknown fields, duplicate or invalid extension names,
+and unsupported versions fail closed. Extensions are consumer-owned names; they
+must describe real receiver authorization/storage behavior rather than silently
+changing generic delivery into a managed destination operation.
+
+The sender probes before offering bytes whenever the header has requirements,
+exceeds the 256 MiB legacy buffered ceiling, or an accepted job exceeds its
+current sender size limit. An unsupported verdict rejects before opening an
+accepted source or allocating a receive sink. A legacy peer that ignores the
+probe produces an actionable error after the existing bounded protocol retries;
+OpenRTC still owns admission, routes and connection recovery. Explicit stream/v1
+send and receive reject required-feature metadata before accepting a body.
+
+The receiver derives its admitted maximum from `maxFileBytes` and the sink:
+without a custom streaming sink it never advertises above 256 MiB. With one,
+`receiveCapabilities` may declare durable resume and application extensions.
+A durable-resume claim requires a checkpointing sink; the application must make
+those checkpoints durable and verify reopened prefixes. `completionReceipt`
+support requires the product `hasCompletionReceipt(header, authenticatedPeer)`
+callback. When a job requires receipts, completion checks that callback after
+publication/commit and rejects success if the receipt is still missing. Neither
+the SDK's in-memory completed map nor a capability declaration is durable proof.
+An absent or aborted receive subscription advertises `receiveAvailable: false`,
+including for zero-byte files.
+
+OFT2 kind `0x09` carries a capability request: transfer ID, big-endian u32 header
+length and optional immutable JSON header (zero length for a general query).
+Kind `0x0a` carries a big-endian u32 JSON length and a closed version-1 response
+bounded to 4096 bytes: `version`, `durableResume`, `completionReceipt`,
+`extensions`, `receiveAvailable`, and `maxFileBytes` (a nonnegative safe integer).
+Header probes retain the configured header-byte bound but validate size against
+the JavaScript safe-integer ceiling, independently of current body admission.
+
+Before returning capabilities, a header probe checks the authenticated product
+receipt. A matching receipt returns the existing `Completed` frame, even if
+receiving is disabled or current file limits have decreased. An accepted-source
+sender likewise reconciles that receipt before enforcing its current body limit,
+without reopening or resending the source. Immutable header conflicts fail
+closed; replies must match the intended authenticated peer and transfer ID.
+Native codec support does not by itself implement or advertise these execution,
+application extension, authorization, or persistence guarantees.
+
+The staged `BULK_JOB_FLOW_CONTROL_VERSION = 1` contract also accepts
+`beforeSendBody` on an individual `send` or `sendAccepted` call. The runtime
+callback and job callback both run before each body attempt, outside the ACK
+deadline; a job callback cannot override a runtime restriction. Product owners
+retain authorization, execution cancellation, durable counters and policy state.
+Persist `BulkFlowController.snapshot()` before allowing body work and restore it
+into a fresh controller when a durable execution owner changes. Publication and
+consumer capability checks are required before relying on these staged APIs.

package/dist/capabilities.d.ts

@@ -0,0 +1,25 @@
+import type { FileTransferHeader } from './index.js';
+export declare const REQUIRED_CAPABILITIES_METADATA_KEY = "openrtc.required-capabilities.v1";
+export declare const MAX_CAPABILITY_BYTES = 4096;
+export declare const LEGACY_MAX_FILE_BYTES: number;
+export interface TransferRequirements {
+    durableResume?: boolean;
+    completionReceipt?: boolean;
+    extensions?: readonly string[];
+}
+export interface RequiredTransferCapabilities {
+    version: 1;
+    durableResume: boolean;
+    completionReceipt: boolean;
+    extensions: string[];
+}
+export interface TransferCapabilities extends RequiredTransferCapabilities {
+    receiveAvailable: boolean;
+    maxFileBytes: number;
+}
+export declare function requiredCapabilities(value: unknown, wire?: boolean): RequiredTransferCapabilities;
+export declare function transferCapabilities(value: unknown): TransferCapabilities;
+export declare function requiredTransferCapabilities(header: FileTransferHeader): RequiredTransferCapabilities | null;
+export declare function withRequiredCapabilities(header: FileTransferHeader, requirements: TransferRequirements): FileTransferHeader;
+export declare function requireCapabilities(capabilities: TransferCapabilities, header: FileTransferHeader): void;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,eAAO,MAAM,kCAAkC,qCAAqC,CAAC;AACrF,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AACD,MAAM,WAAW,4BAA4B;IACzC,OAAO,EAAE,CAAC,CAAC;IAAC,aAAa,EAAE,OAAO,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;CACxF;AACD,MAAM,WAAW,oBAAqB,SAAQ,4BAA4B;IAAG,gBAAgB,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE;AAe9H,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,UAAQ,GAAG,4BAA4B,CAU/F;AACD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAMzE;AACD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,kBAAkB,GAAG,4BAA4B,GAAG,IAAI,CAM5G;AACD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,GAAG,kBAAkB,CAM3H;AACD,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,oBAAoB,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAMxG"}

package/dist/capabilities.js

@@ -0,0 +1,58 @@
+export const REQUIRED_CAPABILITIES_METADATA_KEY = 'openrtc.required-capabilities.v1';
+export const MAX_CAPABILITY_BYTES = 4096;
+export const LEGACY_MAX_FILE_BYTES = 256 * 1024 * 1024;
+function record(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).some(key => !keys.includes(key)))
+        throw new Error('invalid transfer capability fields');
+    return value;
+}
+function extensions(value) {
+    if (!Array.isArray(value) || value.length > 16 || value.some(item => typeof item !== 'string' || item.length > 128 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(item)))
+        throw new Error('invalid transfer capability extensions');
+    const sorted = [...value].sort();
+    if (sorted.some((item, index) => index > 0 && item === sorted[index - 1]))
+        throw new Error('duplicate transfer capability extension');
+    return sorted;
+}
+export function requiredCapabilities(value, wire = false) {
+    const row = record(value, ['version', 'durableResume', 'completionReceipt', 'extensions']);
+    if (wire ? row.version !== 1 || typeof row.durableResume !== 'boolean'
+        || typeof row.completionReceipt !== 'boolean' || row.extensions === undefined
+        : row.version !== undefined && row.version !== 1
+            || row.durableResume !== undefined && typeof row.durableResume !== 'boolean'
+            || row.completionReceipt !== undefined && typeof row.completionReceipt !== 'boolean')
+        throw new Error('invalid transfer capability version or flags');
+    return { version: 1, durableResume: row.durableResume === true, completionReceipt: row.completionReceipt === true,
+        extensions: extensions(row.extensions ?? []) };
+}
+export function transferCapabilities(value) {
+    const row = record(value, ['version', 'maxFileBytes', 'receiveAvailable', 'durableResume', 'completionReceipt', 'extensions']);
+    if (typeof row.receiveAvailable !== 'boolean' || !Number.isSafeInteger(row.maxFileBytes) || row.maxFileBytes < 0)
+        throw new Error('invalid transfer capability file limit');
+    return { ...requiredCapabilities({ version: row.version, durableResume: row.durableResume,
+            completionReceipt: row.completionReceipt, extensions: row.extensions }, true), receiveAvailable: row.receiveAvailable, maxFileBytes: row.maxFileBytes };
+}
+export function requiredTransferCapabilities(header) {
+    const encoded = header.metadata?.[REQUIRED_CAPABILITIES_METADATA_KEY];
+    if (encoded === undefined)
+        return null;
+    if (typeof encoded !== 'string' || new TextEncoder().encode(encoded).byteLength > MAX_CAPABILITY_BYTES)
+        throw new Error('invalid required transfer capability metadata');
+    return requiredCapabilities(JSON.parse(encoded), true);
+}
+export function withRequiredCapabilities(header, requirements) {
+    const encoded = JSON.stringify(requiredCapabilities(requirements));
+    const old = header.metadata?.[REQUIRED_CAPABILITIES_METADATA_KEY];
+    if (old !== undefined && old !== encoded)
+        throw new Error('transfer_identity_conflict: required transfer capabilities differ from the accepted header');
+    return { ...header, metadata: { ...header.metadata, [REQUIRED_CAPABILITIES_METADATA_KEY]: encoded } };
+}
+export function requireCapabilities(capabilities, header) {
+    const required = requiredTransferCapabilities(header);
+    if (!capabilities.receiveAvailable || header.size > capabilities.maxFileBytes || required?.durableResume && !capabilities.durableResume
+        || required?.completionReceipt && !capabilities.completionReceipt
+        || required?.extensions.some(extension => !capabilities.extensions.includes(extension)))
+        throw new Error('transfer_capability_required: receiver cannot admit the selected size or required transfer features');
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/flowControl.d.ts

@@ -0,0 +1,45 @@
+/** Application bulk-body pacing only. Admission, ACKs, and lifecycle messages
+ * bypass this controller. Share one instance across all bulk work in a runtime. */
+export type BulkDirection = 'upload' | 'download';
+export interface BulkRates {
+    uploadBytesPerSecond: number | null;
+    downloadBytesPerSecond: number | null;
+}
+export interface BulkFlowSnapshot {
+    version: 1;
+    burstBytes: number;
+    upload: {
+        rate: number | null;
+        tokens: number;
+    };
+    download: {
+        rate: number | null;
+        tokens: number;
+    };
+}
+export declare class BulkFlowController {
+    readonly burstBytes: number;
+    private readonly maxPending;
+    private readonly states;
+    private readonly changes;
+    private pending;
+    private used;
+    constructor(rates?: BulkRates, burstBytes?: number, maxPending?: number);
+    configure(rates: BulkRates): void;
+    /** Product storage owns durability and wall-clock elapsed time. Export
+     * after acquisition and persist before allowing the body attempt. Pending
+     * requests are not grants and are deliberately excluded. */
+    snapshot(): BulkFlowSnapshot;
+    /** Restore into a fresh owner only; switching execution owners must not
+     * mint a new burst. The caller supplies conservative offline elapsed time. */
+    restore(raw: unknown, elapsedMs: number): void;
+    /** Wait before submitting a bounded body slice to a transport. Control
+     * deadlines start after this wait; cancellation never authorizes a slice. */
+    acquire(direction: BulkDirection, peer: string, bytes: number, signal?: AbortSignal): Promise<void>;
+    /** Admit all applicable budgets synchronously, before any token debit.
+     * Product owners retain/persist these controllers across job handoff. */
+    acquireWith(direction: BulkDirection, peer: string, bytes: number, constraints: readonly BulkFlowController[], signal?: AbortSignal): Promise<void>;
+    private refill;
+    private pump;
+}
+//# sourceMappingURL=flowControl.d.ts.map

package/dist/flowControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowControl.d.ts","sourceRoot":"","sources":["../src/flowControl.ts"],"names":[],"mappings":"AAAA;mFACmF;AACnF,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAClD,MAAM,WAAW,SAAS;IAAG,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AACzG,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAMD,qBAAa,kBAAkB;IAMvB,QAAQ,CAAC,UAAU;IAAc,OAAO,CAAC,QAAQ,CAAC,UAAU;IALhE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsE;IAC9F,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,IAAI,CAAS;gBACT,KAAK,GAAE,SAAwE,EAC9E,UAAU,SAAY,EAAmB,UAAU,SAAO;IASvE,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAcjC;;gEAE4D;IAC5D,QAAQ,IAAI,gBAAgB;IAM5B;kFAC8E;IAC9E,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAsB9C;iFAC6E;IAC7E,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAGnG;6EACyE;IACzE,WAAW,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAC7D,WAAW,EAAE,SAAS,kBAAkB,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCpF,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,IAAI;CA4Cf"}

package/dist/flowControl.js

@@ -0,0 +1,192 @@
+export class BulkFlowController {
+    constructor(rates = { uploadBytesPerSecond: null, downloadBytesPerSecond: null }, burstBytes = 64 * 1024, maxPending = 4096) {
+        this.burstBytes = burstBytes;
+        this.maxPending = maxPending;
+        this.changes = { upload: new Set(), download: new Set() };
+        this.pending = 0;
+        this.used = false;
+        if (!Number.isSafeInteger(burstBytes) || burstBytes < 1 || burstBytes > 64 * 1024
+            || !Number.isSafeInteger(maxPending) || maxPending < 1 || maxPending > 4096)
+            throw new Error('Invalid bulk flow resource bound');
+        const state = () => ({ rate: null, tokens: burstBytes,
+            updatedAt: performance.now(), peers: new Map(), order: [] });
+        this.states = { upload: state(), download: state() };
+        this.configure(rates);
+    }
+    configure(rates) {
+        for (const direction of ['upload', 'download']) {
+            const rate = rates[`${direction}BytesPerSecond`];
+            if (rate !== null && (!Number.isSafeInteger(rate) || rate <= 0))
+                throw new Error('Bulk rate must be unset or a positive safe integer');
+        }
+        for (const direction of ['upload', 'download']) {
+            const state = this.states[direction];
+            this.refill(state);
+            state.rate = rates[`${direction}BytesPerSecond`];
+            this.pump(direction);
+            for (const changed of this.changes[direction])
+                changed();
+        }
+    }
+    /** Product storage owns durability and wall-clock elapsed time. Export
+     * after acquisition and persist before allowing the body attempt. Pending
+     * requests are not grants and are deliberately excluded. */
+    snapshot() {
+        this.refill(this.states.upload);
+        this.refill(this.states.download);
+        const value = (direction) => ({ rate: this.states[direction].rate,
+            tokens: this.states[direction].tokens });
+        return { version: 1, burstBytes: this.burstBytes, upload: value('upload'), download: value('download') };
+    }
+    /** Restore into a fresh owner only; switching execution owners must not
+     * mint a new burst. The caller supplies conservative offline elapsed time. */
+    restore(raw, elapsedMs) {
+        if (this.used || !Number.isFinite(elapsedMs) || elapsedMs < 0)
+            throw new Error('Invalid bulk flow restoration');
+        const saved = raw;
+        if (saved?.version !== 1 || saved.burstBytes !== this.burstBytes)
+            throw new Error('Unsupported bulk flow state');
+        for (const direction of ['upload', 'download']) {
+            const value = saved[direction];
+            if (!value || (value.rate !== null && (!Number.isSafeInteger(value.rate) || value.rate <= 0))
+                || !Number.isFinite(value.tokens) || value.tokens < 0 || value.tokens > this.burstBytes)
+                throw new Error('Invalid bulk flow state');
+        }
+        const now = performance.now();
+        for (const direction of ['upload', 'download']) {
+            const value = saved[direction], state = this.states[direction];
+            state.rate = value.rate;
+            state.tokens = value.rate === null ? value.tokens : Math.min(this.burstBytes, value.tokens + elapsedMs * value.rate / 1000);
+            state.updatedAt = now;
+        }
+        this.used = true;
+    }
+    /** Wait before submitting a bounded body slice to a transport. Control
+     * deadlines start after this wait; cancellation never authorizes a slice. */
+    acquire(direction, peer, bytes, signal) {
+        return this.acquireWith(direction, peer, bytes, [], signal);
+    }
+    /** Admit all applicable budgets synchronously, before any token debit.
+     * Product owners retain/persist these controllers across job handoff. */
+    acquireWith(direction, peer, bytes, constraints, signal) {
+        if (!Array.isArray(constraints) || constraints.length > 16 || new Set(constraints).size !== constraints.length
+            || constraints.some(flow => !(flow instanceof BulkFlowController) || flow === this || bytes > flow.burstBytes))
+            return Promise.reject(new Error('Invalid bulk flow constraints'));
+        if (!this.states[direction] || !peer || peer.length > 512 || !Number.isSafeInteger(bytes)
+            || bytes < 0 || bytes > this.burstBytes)
+            return Promise.reject(new Error('Invalid bulk body slice'));
+        if (signal?.aborted)
+            return Promise.reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+        if (!bytes)
+            return Promise.resolve();
+        this.used = true;
+        for (const flow of constraints)
+            flow.used = true;
+        if (this.pending >= this.maxPending)
+            return Promise.reject(new Error('receiver_busy: bulk flow queue is full'));
+        const state = this.states[direction];
+        return new Promise((resolve, reject) => {
+            const wake = () => this.pump(direction);
+            const dependencies = [...constraints];
+            for (const flow of dependencies)
+                flow.changes[direction].add(wake);
+            const request = { bytes, resolve, reject, signal, constraints: dependencies,
+                release: () => { for (const flow of dependencies)
+                    flow.changes[direction].delete(wake); } };
+            const queue = state.peers.get(peer) ?? [];
+            if (!queue.length) {
+                state.peers.set(peer, queue);
+                state.order.push(peer);
+            }
+            queue.push(request);
+            this.pending++;
+            if (signal) {
+                request.abort = () => {
+                    const index = queue.indexOf(request);
+                    if (index < 0)
+                        return;
+                    queue.splice(index, 1);
+                    this.pending--;
+                    signal.removeEventListener('abort', request.abort);
+                    if (!queue.length) {
+                        state.peers.delete(peer);
+                        state.order = state.order.filter(value => value !== peer);
+                    }
+                    request.release();
+                    reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+                    this.pump(direction);
+                };
+                signal.addEventListener('abort', request.abort, { once: true });
+            }
+            this.pump(direction);
+        });
+    }
+    refill(state) {
+        const now = performance.now();
+        if (state.rate !== null)
+            state.tokens = Math.min(this.burstBytes, state.tokens + Math.max(0, now - state.updatedAt) * state.rate / 1000);
+        state.updatedAt = now;
+    }
+    pump(direction) {
+        const state = this.states[direction];
+        if (state.timer !== undefined) {
+            clearTimeout(state.timer);
+            state.timer = undefined;
+        }
+        this.refill(state);
+        let blocked = 0, nextWait;
+        while (state.order.length && blocked < state.order.length) {
+            const peer = state.order[0], queue = state.peers.get(peer);
+            const request = queue[0];
+            const globalWait = state.rate !== null && state.tokens + 1e-9 < request.bytes
+                ? (request.bytes - state.tokens) * 1000 / state.rate : undefined;
+            let constraintWait;
+            for (const flow of request.constraints) {
+                const child = flow.states[direction];
+                flow.refill(child);
+                if (child.rate !== null && child.tokens + 1e-9 < request.bytes) {
+                    const wait = (request.bytes - child.tokens) * 1000 / child.rate;
+                    constraintWait = Math.max(constraintWait ?? 0, wait);
+                }
+            }
+            if (constraintWait === undefined && globalWait !== undefined) {
+                // An aggregate-ready large slice keeps its turn; small slices
+                // cannot repeatedly consume its earned global credit.
+                nextWait = Math.min(nextWait ?? Infinity, globalWait);
+                break;
+            }
+            if (constraintWait !== undefined) {
+                // A job-blocked slice reserves nothing. Rotate only this
+                // ineligible peer so unrelated ready work can use its turn.
+                nextWait = Math.min(nextWait ?? Infinity, Math.max(globalWait ?? 0, constraintWait));
+                state.order.push(state.order.shift());
+                blocked++;
+                continue;
+            }
+            if (state.rate !== null)
+                state.tokens = Math.max(0, state.tokens - request.bytes);
+            for (const flow of request.constraints) {
+                const child = flow.states[direction];
+                if (child.rate !== null)
+                    child.tokens = Math.max(0, child.tokens - request.bytes);
+            }
+            queue.shift();
+            state.order.shift();
+            this.pending--;
+            if (queue.length)
+                state.order.push(peer);
+            else
+                state.peers.delete(peer);
+            if (request.abort)
+                request.signal?.removeEventListener('abort', request.abort);
+            request.release();
+            request.resolve();
+            blocked = 0;
+        }
+        if (state.order.length && nextWait !== undefined) {
+            const waitMs = Math.max(1, Math.ceil(nextWait));
+            state.timer = setTimeout(() => { state.timer = undefined; this.pump(direction); }, Math.min(waitMs, 2147483647));
+        }
+    }
+}
+//# sourceMappingURL=flowControl.js.map

package/dist/flowControl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowControl.js","sourceRoot":"","sources":["../src/flowControl.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,15 @@
+import { type TransferCapabilities, type TransferRequirements } from './capabilities.js';
+export { requiredTransferCapabilities, withRequiredCapabilities, REQUIRED_CAPABILITIES_METADATA_KEY, LEGACY_MAX_FILE_BYTES } from './capabilities.js';
+export type { TransferCapabilities, TransferRequirements, RequiredTransferCapabilities } from './capabilities.js';
 import type { Avenue } from 'openrtc';
 import type { ChannelDescriptor, RuntimeClient } from 'openrtc/runtime';
+/** Checkpoint-before-offset and product-commit-before-completion semantics. */
+export declare const DURABLE_DELIVERY_VERSION: 1;
+/** Per-sink body policy, legacy admission and execution cancellation. */
+export declare const BULK_RECEIVE_FLOW_CONTROL_VERSION: 1;
+export declare const BULK_RECEIVE_ADMISSION_WAIT_VERSION: 1;
+/** Unpaced stream/v1 sink policy and idle execution retirement. */
+export declare const BULK_STREAM_RECEIVE_FLOW_CONTROL_VERSION: 1;
 /** File transfer binds to one already-active 2.0 capability avenue. */
 export type TransferClient = Pick<Avenue, 'channels' | 'diagnostics' | 'peers'> & {
     /** Stable, route-level application intake for replaceable connection wrappers. */
@@ -12,6 +22,12 @@ export type TransferClient = Pick<Avenue, 'channels' | 'diagnostics' | 'peers'>
  */
 export declare function transferFromRuntime(runtime: RuntimeClient): TransferClient;
 export declare const CHANNEL: ChannelDescriptor;
+export declare const RECEIVER_WAIT_METADATA_KEY = "openrtc.receive-wait";
+export declare const MAX_RECEIVER_WAIT_LEASE_MS = 60000;
+/** Persist this capability as part of the immutable offer before acceptance. */
+export declare function withReceiverWaitCapability(header: FileTransferHeader): FileTransferHeader;
+export declare const MAX_TRANSFER_CHUNK_BYTES: number;
+export declare const MAX_TRANSFER_WINDOW_CHUNKS = 64;
 export interface FileTransferHeader {
     version: 1;
     transferId: string;
@@ -40,10 +56,22 @@ export interface ReceivedFile {
     remoteNodeId: string;
 }
 export interface ReceiveSink<Result = unknown> {
+    /** Product execution policy for this accepted receive. Unpaced legacy
+     * offers may opt out of wait negotiation; their callback must not wait for
+     * rate credit and must reject if a later policy requires it. */
+    bodyPolicy?: {
+        requiresReceiverWait: boolean;
+        signal: AbortSignal;
+        beforeAttempt(attempt: TransferReceiveBodyAttempt): Promise<void>;
+    };
     /** Must equal the requested header offset for a resumed transfer. */
     resumeOffset?: number;
     write(chunk: Uint8Array): Promise<void>;
+    /** Persist the accepted prefix before the protocol advertises its offset. */
+    checkpoint?(): Promise<void>;
     close(): Promise<Result>;
+    /** Commit the product receipt after verification and history publication. */
+    commit?(): Promise<void>;
     abort(reason: unknown): Promise<void>;
     /** Verify a sender-declared digest without requiring WebView buffering. */
     verifySha256?(expectedHex: string): Promise<boolean>;
@@ -62,14 +90,63 @@ export interface TransferOptions<Result = ReceivedFile> {
     maxFileBytes?: number;
     /** Maximum time to wait for the receiver's persisted-and-verified ACK. */
     ackTimeoutMs?: number;
-    createReceiveSink?: (header: FileTransferHeader, remoteNodeId: string) => Promise<ReceiveSink<Result>>;
+    createReceiveSink?: (header: FileTransferHeader, remoteNodeId: string, signal?: AbortSignal) => Promise<ReceiveSink<Result>>;
+    /** Product-owned durable receipt lookup on the authenticated peer scope. */
+    hasCompletionReceipt?: (header: FileTransferHeader, remoteNodeId: string) => Promise<boolean>;
+    /** Application aggregate pacing/quota checkpoint before each body attempt.
+     * Runs outside the receiver-ACK deadline; headers and controls bypass it. */
+    beforeSendBody?: (attempt: TransferBodyAttempt) => Promise<void>;
+    /** Routed receivers pace/quota-check body work without granting a durable
+     * offset. Legacy offers are refused before sink acceptance unless a retained
+     * completion receipt exists. The callback must honor its execution signal. */
+    beforeReceiveBody?: (attempt: TransferReceiveBodyAttempt) => Promise<void>;
+    /** Each negotiated wait lease is bounded; only live receiver work renews it. */
+    receiveWaitLeaseMs?: number;
+    /** Claims belong to the product sink/authorization owner, never transport.
+     * A durable-resume claim requires an installed streaming receive sink. */
+    receiveCapabilities?: {
+        durableResume?: boolean;
+        extensions?: readonly string[];
+    };
 }
+export interface TransferBodyAttempt {
+    /** Source position of this immutable body slice; absent on older adapters. */
+    offset?: number;
+    transferId: string;
+    /** Target peer selector supplied to send(); the runtime resolves identity. */
+    peerId: string;
+    bytes: number;
+    signal?: AbortSignal;
+}
+export interface TransferReceiveBodyAttempt {
+    transferId: string;
+    remoteNodeId: string;
+    offset: number;
+    bytes: number;
+    signal: AbortSignal;
+}
+export { BulkFlowController } from './flowControl.js';
+export type { BulkDirection, BulkRates, BulkFlowSnapshot } from './flowControl.js';
+export declare const BULK_SEND_FLOW_CONTROL_VERSION = 1;
+export declare const BULK_JOB_FLOW_CONTROL_VERSION = 1;
+export declare const BULK_SCOPED_FLOW_CONTROL_VERSION = 1;
+/** Product-persisted immutable offer. Body access is deferred until the
+ * authenticated receiver requests bytes rather than returning its receipt. */
+export interface AcceptedFileSource {
+    header: FileTransferHeader;
+    openSource(): Promise<File>;
+}
+export type AcceptedSendOptions = Pick<SendFileOptions, 'signal' | 'onProgress' | 'beforeSendBody'>;
 export interface SendFileOptions {
     transferId?: string;
+    requiredCapabilities?: TransferRequirements;
     metadata?: Record<string, string>;
     integrity?: 'none' | 'sha256';
     offsetBytes?: number;
     signal?: AbortSignal;
+    /** Product execution-specific policy, in addition to the runtime policy.
+     * Both complete before a body attempt and outside the receiver ACK timer. */
+    beforeSendBody?: (attempt: TransferBodyAttempt) => Promise<void>;
     onProgress?: (progress: TransferProgress) => void;
 }
 export interface ReceiveFileOptions<Result> {
@@ -81,6 +158,14 @@ export interface ReceiveFileOptions<Result> {
 export type RoutedTransferFrame = {
     kind: 'offer';
     header: FileTransferHeader;
+} | {
+    kind: 'capabilities-request';
+    transferId: string;
+    header?: FileTransferHeader;
+} | {
+    kind: 'capabilities';
+    transferId: string;
+    capabilities: TransferCapabilities;
 } | {
     kind: 'resume';
     transferId: string;
@@ -95,6 +180,11 @@ export type RoutedTransferFrame = {
     kind: 'ack';
     transferId: string;
     offset: number;
+} | {
+    kind: 'waiting';
+    transferId: string;
+    offset: number;
+    leaseMs: number;
 } | {
     kind: 'complete';
     transferId: string;
@@ -117,6 +207,7 @@ export interface TransferRouteOptions<Result = ReceivedFile> extends TransferOpt
 export declare function encodeFrame(frame: RoutedTransferFrame, maxHeaderBytes?: number, maxChunkBytes?: number): Uint8Array;
 export declare function decodeFrame(input: Uint8Array, maxFileBytes?: number, maxHeaderBytes?: number, maxChunkBytes?: number): RoutedTransferFrame | null;
 export declare function createTransfer<Result = ReceivedFile>(client: TransferClient, options?: TransferRouteOptions<Result>): {
+    sendAccepted(deviceId: string, source: AcceptedFileSource, sendOptions?: AcceptedSendOptions): Promise<string>;
     send(deviceId: string, file: File, sendOptions?: SendFileOptions): Promise<string>;
     onIncoming(configured: ReceiveFileOptions<Result>): () => void;
     dispose(): void;
@@ -128,6 +219,7 @@ export declare function createTransfer<Result = ReceivedFile>(client: TransferCl
  * the consumer remains responsible for persisting the surrounding intent.
  */
 export declare function createRoutedTransfer<Result = ReceivedFile>(client: TransferClient, options?: TransferRouteOptions<Result>): {
+    sendAccepted(deviceId: string, source: AcceptedFileSource, sendOptions?: AcceptedSendOptions): Promise<string>;
     send(deviceId: string, file: File, sendOptions?: SendFileOptions): Promise<string>;
     onIncoming(configured: ReceiveFileOptions<Result>): () => void;
     dispose(): void;