wire-mesh-core 4.1.5 → 4.2.0

package/README.md

@@ -16,6 +16,7 @@ The TypeScript implementation of wire-mesh's protocol, built ports/adapters: dom
 - **Peer-advert verification** (`src/domain/peer-advert.ts`): the two checks transport.cddl states for a gossiped advert, applied by the relay hub before it registers or forwards one and by every session before one reaches its directory: the embedded identity-key self-certifies (`sha256(identity-key.public-key) == device`), and the signature verifies under that same key over the domain-separated canonical encoding of the advert with its signature removed, which covers the open extension tail as well. Deliberately not tokens.cddl's COSE Sig_structure: an advert's open tail lets an attacker craft one whose encoding also satisfies token-claims, so the prefixed construction keeps the two byte strings disjoint. Reaches a verdict for every input rather than throwing, since an advert's algorithm and key bytes are attacker-chosen.
 - **Secure channel** (`src/domain/secure-channel.ts`, `src/domain/relay-channels.ts`): the end-to-end channel spec/secure-channel.cddl defines between two devices that reach each other through a relay. A session opens one with each peer it addresses through a relay pairing, seals every manage-request, manage-response and core/data frame in it, drops any that arrives as plain relay-data, and attributes a request to the identity the peer's handshake proved rather than to the `from-device` a hub stamps. There is no plaintext fallback, so a peer that does not speak it cannot be reached through a relay.
 - **Relay hub** (`src/domain/relay-hub.ts`, `src/domain/relay-pairing.ts`, `src/domain/hub-mailbox.ts`): the hub's relay role against the Transport port alone. It verifies every gossiped advert before registering, forwarding or replaying it, pairs devices for relayed traffic, and, as a mailbox, replicates the `core/data` logs of devices that are offline.
+- **Consuming incoming streams** (`src/domain/consume-incoming.ts`, `src/domain/fault-report.ts`): the one way to read a session's incoming streams (`incomingManageRequests`, `incomingDataFrames`, `revocationAnnouncements`, `coordinatorFrames`, `events`). `consumeEach` handles each item in order and contains a failure while handling one, so it never ends the loop or rejects to whoever started it; `serveManageRequests` also answers a request whose handling failed with a fixed `internal-error` refusal that carries no text from the failure. A failure is told to an optional `onFault` callback through a reporter that allows one report per source per interval, with a count of those left out, and that contains a callback that throws or rejects. A loop can be stopped with an `AbortSignal`, which closes the stream's iterator so the stream's next reader takes what the stopped one did not.
 - **Bulk transfer** (`src/domain/bulk.ts`): resumable, flow-controlled `core/bulk` transfer, with a byte-credit window that the receiver's acknowledgements move. `src/domain/sharded-delivery.ts` composes it with erasure coding (`src/domain/erasure-coding.ts`) and shard manifests (`src/domain/shard-manifest.ts`) to spread a payload across holder devices.
 - **Data sync** (`src/domain/data-sync.ts`): the have, request and entries primitive over a storage-backed oplog, which never accepts a gap. What to broadcast, whose logs to track and which holder to ask are left to the application.
 - **Coordinator election** (`src/domain/coordinator-election.ts`): the gossiped, term-based election over `coordinator-frame`, where a higher term supersedes a lower one and equal terms are broken by lowest device-id.

package/dist/adapters/tls-transport.cjs

@@ -149,6 +149,8 @@ function createTlsTransport(identity) {
 				}, (socket) => {
 					authenticatedPeerDeviceId(socket).then((peerDeviceId) => {
 						onConnection(wrapSocket(socket, peerDeviceId));
+					}).catch((error) => {
+						socket.destroy(error instanceof Error ? error : void 0);
 					});
 				});
 				server.once("error", reject);

package/dist/adapters/tls-transport.mjs

@@ -148,6 +148,8 @@ function createTlsTransport(identity) {
 				}, (socket) => {
 					authenticatedPeerDeviceId(socket).then((peerDeviceId) => {
 						onConnection(wrapSocket(socket, peerDeviceId));
+					}).catch((error) => {
+						socket.destroy(error instanceof Error ? error : void 0);
 					});
 				});
 				server.once("error", reject);

package/dist/domain/async-queue.cjs

@@ -10,19 +10,55 @@ function createAsyncQueue() {
 			else backlog.push(value);
 		},
 		stream: { [Symbol.asyncIterator]() {
-			return { next: async () => new Promise((resolve) => {
-				const backlogValue = backlog.shift();
-				if (backlogValue !== void 0) resolve({
-					value: backlogValue,
-					done: false
-				});
-				else waiters.push((value) => {
-					resolve({
-						value,
-						done: false
+			let finished = false;
+			const releases = /* @__PURE__ */ new Set();
+			return {
+				next: async () => new Promise((resolve) => {
+					if (finished) {
+						resolve({
+							value: void 0,
+							done: true
+						});
+						return;
+					}
+					const backlogValue = backlog.shift();
+					if (backlogValue !== void 0) {
+						resolve({
+							value: backlogValue,
+							done: false
+						});
+						return;
+					}
+					const registration = {};
+					const waiter = (value) => {
+						if (registration.release !== void 0) releases.delete(registration.release);
+						resolve({
+							value,
+							done: false
+						});
+					};
+					registration.release = () => {
+						waiters.splice(waiters.indexOf(waiter), 1);
+						resolve({
+							value: void 0,
+							done: true
+						});
+					};
+					waiters.push(waiter);
+					releases.add(registration.release);
+				}),
+				return: async () => {
+					finished = true;
+					for (const release of [...releases]) {
+						releases.delete(release);
+						release();
+					}
+					return Promise.resolve({
+						value: void 0,
+						done: true
 					});
-				});
-			}) };
+				}
+			};
 		} }
 	};
 }

package/dist/domain/async-queue.d.cts

@@ -1,5 +1,5 @@
 //#region src/domain/async-queue.d.ts
-/** A backlog-plus-waiters async queue: push() delivers to whichever consumer is already waiting on next(), or buffers the value for a consumer that hasn't asked yet. mesh-session.ts used this exact pattern three times over (events, incomingManageRequests, revocationAnnouncements) with nothing session-shaped about it -- extracted here once new features kept pushing that file over this repo's own max-lines lint budget. Never ends on its own (matches every one of mesh-session.ts's own async iterables, none of which the session itself ever closes): a consumer stops by simply not calling next() again. */
+/** A backlog-plus-waiters async queue: push() delivers to whichever consumer is already waiting on next(), or buffers the value for a consumer that hasn't asked yet. mesh-session.ts used this exact pattern three times over (events, incomingManageRequests, revocationAnnouncements) with nothing session-shaped about it -- extracted here once new features kept pushing that file over this repo's own max-lines lint budget. Never ends on its own (matches every one of mesh-session.ts's own async iterables, none of which the session itself ever closes): a consumer stops by calling return() on its iterator, which also withdraws a next() it has waiting. */
 export interface AsyncQueue<T> {
   /** Delivers value to whichever consumer's own next() call is already waiting, or buffers it for the next one that asks. */
   push: (value: T) => void;

package/dist/domain/async-queue.d.mts

@@ -1,5 +1,5 @@
 //#region src/domain/async-queue.d.ts
-/** A backlog-plus-waiters async queue: push() delivers to whichever consumer is already waiting on next(), or buffers the value for a consumer that hasn't asked yet. mesh-session.ts used this exact pattern three times over (events, incomingManageRequests, revocationAnnouncements) with nothing session-shaped about it -- extracted here once new features kept pushing that file over this repo's own max-lines lint budget. Never ends on its own (matches every one of mesh-session.ts's own async iterables, none of which the session itself ever closes): a consumer stops by simply not calling next() again. */
+/** A backlog-plus-waiters async queue: push() delivers to whichever consumer is already waiting on next(), or buffers the value for a consumer that hasn't asked yet. mesh-session.ts used this exact pattern three times over (events, incomingManageRequests, revocationAnnouncements) with nothing session-shaped about it -- extracted here once new features kept pushing that file over this repo's own max-lines lint budget. Never ends on its own (matches every one of mesh-session.ts's own async iterables, none of which the session itself ever closes): a consumer stops by calling return() on its iterator, which also withdraws a next() it has waiting. */
 export interface AsyncQueue<T> {
   /** Delivers value to whichever consumer's own next() call is already waiting, or buffers it for the next one that asks. */
   push: (value: T) => void;

package/dist/domain/async-queue.mjs

@@ -9,19 +9,55 @@ function createAsyncQueue() {
 			else backlog.push(value);
 		},
 		stream: { [Symbol.asyncIterator]() {
-			return { next: async () => new Promise((resolve) => {
-				const backlogValue = backlog.shift();
-				if (backlogValue !== void 0) resolve({
-					value: backlogValue,
-					done: false
-				});
-				else waiters.push((value) => {
-					resolve({
-						value,
-						done: false
+			let finished = false;
+			const releases = /* @__PURE__ */ new Set();
+			return {
+				next: async () => new Promise((resolve) => {
+					if (finished) {
+						resolve({
+							value: void 0,
+							done: true
+						});
+						return;
+					}
+					const backlogValue = backlog.shift();
+					if (backlogValue !== void 0) {
+						resolve({
+							value: backlogValue,
+							done: false
+						});
+						return;
+					}
+					const registration = {};
+					const waiter = (value) => {
+						if (registration.release !== void 0) releases.delete(registration.release);
+						resolve({
+							value,
+							done: false
+						});
+					};
+					registration.release = () => {
+						waiters.splice(waiters.indexOf(waiter), 1);
+						resolve({
+							value: void 0,
+							done: true
+						});
+					};
+					waiters.push(waiter);
+					releases.add(registration.release);
+				}),
+				return: async () => {
+					finished = true;
+					for (const release of [...releases]) {
+						releases.delete(release);
+						release();
+					}
+					return Promise.resolve({
+						value: void 0,
+						done: true
 					});
-				});
-			}) };
+				}
+			};
 		} }
 	};
 }

package/dist/domain/bulk.cjs

@@ -70,33 +70,63 @@ function buildBulkCancelCommand(transferId, capability, reason) {
 		}
 	};
 }
+/** How long a sender waits for the receiver's next ack before giving the stream up as incomplete, so that a receiver that stays connected and goes silent cannot hold the stream, and its registration, for ever. A transfer resumes from the receiver's own ack-seq, so giving up loses nothing. */
+const DEFAULT_ACK_TIMEOUT_MS = 6e4;
 /**
 * Builds a sender coordinator over one `source`. A caller sending several independent transfers from different sources constructs one sender per source, mirroring createCapabilityRequestHandler's own one-instance-per-capability convention.
 */
 function createBulkSender(options) {
 	const pendingAcks = /* @__PURE__ */ new Map();
 	const cancelled = /* @__PURE__ */ new Set();
+	/** Connections whose receive ended. A transfer started over one, or an ack awaited after it ended, is incomplete at once: nothing will ever deliver an ack over it. */
+	const ended = /* @__PURE__ */ new WeakSet();
 	function resolveNextAck(id, frame) {
 		const queue = pendingAcks.get(id);
-		if (queue === void 0 || queue.length === 0) return;
-		queue.shift()?.resolve(frame);
+		const waiter = queue?.shift();
+		if (queue?.length === 0) pendingAcks.delete(id);
+		waiter?.resolve(frame);
 	}
 	function rejectAllAcks(id, error) {
 		const queue = pendingAcks.get(id);
 		if (queue === void 0) return;
-		pendingAcks.set(id, []);
+		pendingAcks.delete(id);
 		for (const waiter of queue) waiter.reject(error);
 	}
+	/** Resolves with the next ack for `id`. Rejects when the connection ends or when `ackTimeoutMs` passes first, removing its registration either way, and the transfer's entry goes with its last registration. */
 	async function waitForAck(id) {
 		return new Promise((resolve, reject) => {
 			const queue = pendingAcks.get(id) ?? [];
-			queue.push({
-				resolve,
-				reject
-			});
+			const timer = {};
+			const entry = {
+				resolve: (frame) => {
+					clearTimeout(timer.handle);
+					resolve(frame);
+				},
+				reject: (error) => {
+					clearTimeout(timer.handle);
+					reject(error);
+				}
+			};
+			timer.handle = setTimeout(() => {
+				remove(id, entry);
+				reject(/* @__PURE__ */ new Error("timed out waiting for the receiver's ack"));
+			}, options.ackTimeoutMs ?? 6e4);
+			queue.push(entry);
 			pendingAcks.set(id, queue);
 		});
 	}
+	/** waitForAck over a connection: refused at once when that connection has already ended. */
+	async function waitForAckOver(connection, id) {
+		if (ended.has(connection)) throw new Error("connection ended");
+		return waitForAck(id);
+	}
+	function remove(id, entry) {
+		const queue = pendingAcks.get(id);
+		if (queue === void 0) return;
+		const index = queue.indexOf(entry);
+		if (index !== -1) queue.splice(index, 1);
+		if (queue.length === 0) pendingAcks.delete(id);
+	}
 	async function stream(connection, transferId, fromSeq, initialWindow) {
 		const id = transferIdHex(transferId);
 		let seq = fromSeq;
@@ -116,7 +146,7 @@ function createBulkSender(options) {
 		const exceedsWindow = (length) => bytesInFlight + length > window;
 		/** Takes acks until `length` more bytes fit in the window. */
 		const awaitCredit = async (length) => {
-			applyAck(await waitForAck(id));
+			applyAck(await waitForAckOver(connection, id));
 			if (exceedsWindow(length)) await awaitCredit(length);
 		};
 		try {
@@ -126,7 +156,7 @@ function createBulkSender(options) {
 					ackedCount
 				};
 				if (exceedsWindow(chunk.length)) {
-					applyAck(await waitForAck(id));
+					applyAck(await waitForAckOver(connection, id));
 					if (exceedsWindow(chunk.length)) await awaitCredit(chunk.length);
 				}
 				const dataFrame = {
@@ -164,7 +194,15 @@ function createBulkSender(options) {
 	}
 	/** Waits for the receiver's own post-accept bulk-ack -- ack-seq is a count of chunks durably persisted so far, so it doubles as the seq to resume streaming from with no adjustment -- and starts streaming from there. Shared by open() (after bulk.open is accepted, where the very first ack's own ack-seq is naturally 0 for a fresh transfer) and continueFrom() (after a bulk.resume is accepted), since a receiver sends this identical proactive ack in both cases per spec/bulk.cddl's own bulk-ack-frame comment. */
 	async function resumeStream(connection, transferId) {
-		const ack = await waitForAck(transferIdHex(transferId));
+		let ack;
+		try {
+			ack = await waitForAckOver(connection, transferIdHex(transferId));
+		} catch {
+			return {
+				status: "incomplete",
+				ackedCount: 0
+			};
+		}
 		return stream(connection, transferId, ack["ack-seq"], ack.window);
 	}
 	let activeTransferId;
@@ -175,6 +213,7 @@ function createBulkSender(options) {
 			resolveNextAck(transferIdHex(frame["transfer-id"]), frame);
 		},
 		onConnectionEnd(connection) {
+			ended.add(connection);
 			if (activeTransferId === void 0 || activeConnection !== connection) return;
 			rejectAllAcks(activeTransferId, /* @__PURE__ */ new Error("connection ended"));
 		},
@@ -427,6 +466,7 @@ function createBulkReceiver(options) {
 //#endregion
 exports.BULK_READ_CAPABILITY = BULK_READ_CAPABILITY;
 exports.BULK_WRITE_CAPABILITY = BULK_WRITE_CAPABILITY;
+exports.DEFAULT_ACK_TIMEOUT_MS = DEFAULT_ACK_TIMEOUT_MS;
 exports.buildBulkCancelCommand = buildBulkCancelCommand;
 exports.buildBulkOpenCommand = buildBulkOpenCommand;
 exports.buildBulkResumeCommand = buildBulkResumeCommand;

package/dist/domain/bulk.d.cts

@@ -24,7 +24,11 @@ export interface CreateBulkSenderOptions {
    * Yields every chunk of the transfer starting at `fromSeq` (0 for a fresh transfer) -- MUST be callable more than once, from any previously-reached seq, and yield the identical bytes each time (spec/bulk.cddl's own "a file is inherently durable/re-readable" design point): this is what makes both mid-transfer resume and the post-transfer digest re-derivation below correct without this module buffering the whole transfer in memory during the send itself.
    */
   source: (fromSeq: number) => AsyncIterable<Uint8Array<ArrayBuffer>>;
+  /** How long to wait for each ack before the stream returns "incomplete"; DEFAULT_ACK_TIMEOUT_MS when absent. */
+  ackTimeoutMs?: number;
 }
+/** How long a sender waits for the receiver's next ack before giving the stream up as incomplete, so that a receiver that stays connected and goes silent cannot hold the stream, and its registration, for ever. A transfer resumes from the receiver's own ack-seq, so giving up loses nothing. */
+export declare const DEFAULT_ACK_TIMEOUT_MS = 60000;
 export interface BulkSenderOpenOptions {
   transferId?: Uint8Array<ArrayBuffer>;
   totalSize?: number;

package/dist/domain/bulk.d.mts

@@ -24,7 +24,11 @@ export interface CreateBulkSenderOptions {
    * Yields every chunk of the transfer starting at `fromSeq` (0 for a fresh transfer) -- MUST be callable more than once, from any previously-reached seq, and yield the identical bytes each time (spec/bulk.cddl's own "a file is inherently durable/re-readable" design point): this is what makes both mid-transfer resume and the post-transfer digest re-derivation below correct without this module buffering the whole transfer in memory during the send itself.
    */
   source: (fromSeq: number) => AsyncIterable<Uint8Array<ArrayBuffer>>;
+  /** How long to wait for each ack before the stream returns "incomplete"; DEFAULT_ACK_TIMEOUT_MS when absent. */
+  ackTimeoutMs?: number;
 }
+/** How long a sender waits for the receiver's next ack before giving the stream up as incomplete, so that a receiver that stays connected and goes silent cannot hold the stream, and its registration, for ever. A transfer resumes from the receiver's own ack-seq, so giving up loses nothing. */
+export declare const DEFAULT_ACK_TIMEOUT_MS = 60000;
 export interface BulkSenderOpenOptions {
   transferId?: Uint8Array<ArrayBuffer>;
   totalSize?: number;

package/dist/domain/bulk.mjs

@@ -69,33 +69,63 @@ function buildBulkCancelCommand(transferId, capability, reason) {
 		}
 	};
 }
+/** How long a sender waits for the receiver's next ack before giving the stream up as incomplete, so that a receiver that stays connected and goes silent cannot hold the stream, and its registration, for ever. A transfer resumes from the receiver's own ack-seq, so giving up loses nothing. */
+const DEFAULT_ACK_TIMEOUT_MS = 6e4;
 /**
 * Builds a sender coordinator over one `source`. A caller sending several independent transfers from different sources constructs one sender per source, mirroring createCapabilityRequestHandler's own one-instance-per-capability convention.
 */
 function createBulkSender(options) {
 	const pendingAcks = /* @__PURE__ */ new Map();
 	const cancelled = /* @__PURE__ */ new Set();
+	/** Connections whose receive ended. A transfer started over one, or an ack awaited after it ended, is incomplete at once: nothing will ever deliver an ack over it. */
+	const ended = /* @__PURE__ */ new WeakSet();
 	function resolveNextAck(id, frame) {
 		const queue = pendingAcks.get(id);
-		if (queue === void 0 || queue.length === 0) return;
-		queue.shift()?.resolve(frame);
+		const waiter = queue?.shift();
+		if (queue?.length === 0) pendingAcks.delete(id);
+		waiter?.resolve(frame);
 	}
 	function rejectAllAcks(id, error) {
 		const queue = pendingAcks.get(id);
 		if (queue === void 0) return;
-		pendingAcks.set(id, []);
+		pendingAcks.delete(id);
 		for (const waiter of queue) waiter.reject(error);
 	}
+	/** Resolves with the next ack for `id`. Rejects when the connection ends or when `ackTimeoutMs` passes first, removing its registration either way, and the transfer's entry goes with its last registration. */
 	async function waitForAck(id) {
 		return new Promise((resolve, reject) => {
 			const queue = pendingAcks.get(id) ?? [];
-			queue.push({
-				resolve,
-				reject
-			});
+			const timer = {};
+			const entry = {
+				resolve: (frame) => {
+					clearTimeout(timer.handle);
+					resolve(frame);
+				},
+				reject: (error) => {
+					clearTimeout(timer.handle);
+					reject(error);
+				}
+			};
+			timer.handle = setTimeout(() => {
+				remove(id, entry);
+				reject(/* @__PURE__ */ new Error("timed out waiting for the receiver's ack"));
+			}, options.ackTimeoutMs ?? 6e4);
+			queue.push(entry);
 			pendingAcks.set(id, queue);
 		});
 	}
+	/** waitForAck over a connection: refused at once when that connection has already ended. */
+	async function waitForAckOver(connection, id) {
+		if (ended.has(connection)) throw new Error("connection ended");
+		return waitForAck(id);
+	}
+	function remove(id, entry) {
+		const queue = pendingAcks.get(id);
+		if (queue === void 0) return;
+		const index = queue.indexOf(entry);
+		if (index !== -1) queue.splice(index, 1);
+		if (queue.length === 0) pendingAcks.delete(id);
+	}
 	async function stream(connection, transferId, fromSeq, initialWindow) {
 		const id = transferIdHex(transferId);
 		let seq = fromSeq;
@@ -115,7 +145,7 @@ function createBulkSender(options) {
 		const exceedsWindow = (length) => bytesInFlight + length > window;
 		/** Takes acks until `length` more bytes fit in the window. */
 		const awaitCredit = async (length) => {
-			applyAck(await waitForAck(id));
+			applyAck(await waitForAckOver(connection, id));
 			if (exceedsWindow(length)) await awaitCredit(length);
 		};
 		try {
@@ -125,7 +155,7 @@ function createBulkSender(options) {
 					ackedCount
 				};
 				if (exceedsWindow(chunk.length)) {
-					applyAck(await waitForAck(id));
+					applyAck(await waitForAckOver(connection, id));
 					if (exceedsWindow(chunk.length)) await awaitCredit(chunk.length);
 				}
 				const dataFrame = {
@@ -163,7 +193,15 @@ function createBulkSender(options) {
 	}
 	/** Waits for the receiver's own post-accept bulk-ack -- ack-seq is a count of chunks durably persisted so far, so it doubles as the seq to resume streaming from with no adjustment -- and starts streaming from there. Shared by open() (after bulk.open is accepted, where the very first ack's own ack-seq is naturally 0 for a fresh transfer) and continueFrom() (after a bulk.resume is accepted), since a receiver sends this identical proactive ack in both cases per spec/bulk.cddl's own bulk-ack-frame comment. */
 	async function resumeStream(connection, transferId) {
-		const ack = await waitForAck(transferIdHex(transferId));
+		let ack;
+		try {
+			ack = await waitForAckOver(connection, transferIdHex(transferId));
+		} catch {
+			return {
+				status: "incomplete",
+				ackedCount: 0
+			};
+		}
 		return stream(connection, transferId, ack["ack-seq"], ack.window);
 	}
 	let activeTransferId;
@@ -174,6 +212,7 @@ function createBulkSender(options) {
 			resolveNextAck(transferIdHex(frame["transfer-id"]), frame);
 		},
 		onConnectionEnd(connection) {
+			ended.add(connection);
 			if (activeTransferId === void 0 || activeConnection !== connection) return;
 			rejectAllAcks(activeTransferId, /* @__PURE__ */ new Error("connection ended"));
 		},
@@ -424,4 +463,4 @@ function createBulkReceiver(options) {
 	};
 }
 //#endregion
-export { BULK_READ_CAPABILITY, BULK_WRITE_CAPABILITY, buildBulkCancelCommand, buildBulkOpenCommand, buildBulkResumeCommand, createBulkReceiver, createBulkSender, storedTransferSource };
+export { BULK_READ_CAPABILITY, BULK_WRITE_CAPABILITY, DEFAULT_ACK_TIMEOUT_MS, buildBulkCancelCommand, buildBulkOpenCommand, buildBulkResumeCommand, createBulkReceiver, createBulkSender, storedTransferSource };

package/dist/domain/capability-request.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_generated_protocol = require("../generated/protocol.cjs");
 const require_domain_token_scope = require("./token-scope.cjs");
 const require_domain_tokens = require("./tokens.cjs");
+const require_timers = require("../timers-DTJNuBa8.cjs");
 //#region src/domain/capability-request.ts
 /**
 * The generic, capability-agnostic capability-request / capability-grant-ok primitive (wire-mesh#78, spec/management.cddl). Lifts core/room's own room.join shape -- an ungated ask, held open, a human (or any other domain-supplied decision) accepts or refuses, acceptance mints and returns a token on the same response -- out of that one domain so any capability can reuse it, not just room:member. core/room's own room-client.ts is the reference consumer: it rewires requestToJoin/createRoomRouter's room.join handling onto requestCapability/createCapabilityRequestHandler below, supplying room-specific extension fields (its member list) through this module's own extensions mechanism rather than this module knowing anything about rooms.
@@ -14,10 +15,6 @@ function randomTokenId() {
 	crypto.getRandomValues(bytes);
 	return bytes;
 }
-/** Stops a pending timer from keeping the process alive, where the runtime has that notion. Node's setTimeout returns an object with unref(); a browser's or a Worker's returns a number, which has nothing to unref and must not be called as if it did. */
-function unrefIfSupported(handle) {
-	if (typeof handle === "object" && handle !== null && "unref" in handle && typeof handle.unref === "function") Reflect.apply(handle.unref, handle, []);
-}
 /**
 * Builds a capability-request command per management.cddl. The outer `manage-command.verb` is the capability string itself -- the same value as this map's own `params.capability` field -- never a generic literal: capability-verb's own CDDL grammar is a closed alternation of colon-delimited `domain:noun` regexes (spec/tokens.cddl), so a bare literal like "capability" could never satisfy it, and routing by capability (the same way room.send/room.join already share the ROOM_MEMBER_CAPABILITY outer verb) is how a receiver's own per-capability handler knows which grant this ask is even for. `params.verb` is the fixed "capability.request" marker that distinguishes this ask from any other verb sharing the same outer capability (mirroring room.send/room.join's own inner `params.verb` split under one shared outer verb). `valid-until`, when given, bounds how long this ask is worth granting (wire-mesh#82) -- a receiver refuses outright once its own clock has passed it, rather than presenting a stale ask to a human for approval.
 */
@@ -131,7 +128,7 @@ function createCapabilityRequestHandler(options) {
 				message: "no decision within the capability-request timeout"
 			}).catch(() => void 0);
 		}, options.timeoutMs);
-		unrefIfSupported(timeoutHandle);
+		require_timers.unrefIfSupported(timeoutHandle);
 		options.onRequest({
 			scope: incoming.scope,
 			requesterDevice: options.bearerDevice,

package/dist/domain/capability-request.mjs

@@ -1,6 +1,7 @@
 import { capabilityGrantOkSchema, capabilityRequestSchema } from "../generated/protocol.mjs";
 import { scopeNarrows } from "./token-scope.mjs";
 import { mintCapabilityToken, verifyCapabilityToken } from "./tokens.mjs";
+import { t as unrefIfSupported } from "../timers-Q1_kDTyY.mjs";
 //#region src/domain/capability-request.ts
 /**
 * The generic, capability-agnostic capability-request / capability-grant-ok primitive (wire-mesh#78, spec/management.cddl). Lifts core/room's own room.join shape -- an ungated ask, held open, a human (or any other domain-supplied decision) accepts or refuses, acceptance mints and returns a token on the same response -- out of that one domain so any capability can reuse it, not just room:member. core/room's own room-client.ts is the reference consumer: it rewires requestToJoin/createRoomRouter's room.join handling onto requestCapability/createCapabilityRequestHandler below, supplying room-specific extension fields (its member list) through this module's own extensions mechanism rather than this module knowing anything about rooms.
@@ -13,10 +14,6 @@ function randomTokenId() {
 	crypto.getRandomValues(bytes);
 	return bytes;
 }
-/** Stops a pending timer from keeping the process alive, where the runtime has that notion. Node's setTimeout returns an object with unref(); a browser's or a Worker's returns a number, which has nothing to unref and must not be called as if it did. */
-function unrefIfSupported(handle) {
-	if (typeof handle === "object" && handle !== null && "unref" in handle && typeof handle.unref === "function") Reflect.apply(handle.unref, handle, []);
-}
 /**
 * Builds a capability-request command per management.cddl. The outer `manage-command.verb` is the capability string itself -- the same value as this map's own `params.capability` field -- never a generic literal: capability-verb's own CDDL grammar is a closed alternation of colon-delimited `domain:noun` regexes (spec/tokens.cddl), so a bare literal like "capability" could never satisfy it, and routing by capability (the same way room.send/room.join already share the ROOM_MEMBER_CAPABILITY outer verb) is how a receiver's own per-capability handler knows which grant this ask is even for. `params.verb` is the fixed "capability.request" marker that distinguishes this ask from any other verb sharing the same outer capability (mirroring room.send/room.join's own inner `params.verb` split under one shared outer verb). `valid-until`, when given, bounds how long this ask is worth granting (wire-mesh#82) -- a receiver refuses outright once its own clock has passed it, rather than presenting a stale ask to a human for approval.
 */

package/dist/domain/consume-incoming.cjs

@@ -0,0 +1,96 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_device_id = require("./device-id.cjs");
+const require_domain_fault_report = require("./fault-report.cjs");
+//#region src/domain/consume-incoming.ts
+/**
+* The one way to consume a session's incoming streams (incomingManageRequests, incomingDataFrames, revocationAnnouncements, coordinatorFrames, events, or any other async iterable of items): a failure while handling one item is contained to that item, reported once, and the loop goes on to the next, and no rejection escapes to whoever started the loop. A consumer written as a bare `for await` loop ends for good on the first item whose handling throws, and when it was started with `void` the rejection is unhandled, which ends a Node process by default.
+*
+* A failure of the stream itself (the iterator throws, as it does when the session behind it has gone) ends the loop and is reported once with no item. A stream that simply finishes ends the loop without a report.
+*/
+/**
+* Handles each item of `source` in order with `handle`. Resolves when the stream ends, fails or is stopped, and never rejects.
+*
+* Stopping with `signal` closes the stream's iterator at once and ends the loop at the next item boundary. An item the loop has already taken is handled to completion, never discarded, so a stream whose `return()` withdraws a pending wait (the session's own streams do) loses nothing to a later reader. A source whose `return()` cannot settle a pending `next()` (an async generator) ends the loop when that `next()` settles. A failure of the stream itself, or of closing it, is reported once and at once: it is not coalesced with item failures, because it ends the loop and no later report could carry it.
+*/
+async function consumeEach(source, handle, options = {}) {
+	const { onFault, signal } = options;
+	const reporter = require_domain_fault_report.createFaultReporter(options.now);
+	const reportItem = (error, item) => {
+		if (onFault === void 0) return;
+		try {
+			const origin = options.sourceOf?.(item) ?? "";
+			reporter(origin, async (suppressed) => onFault(error, item, suppressed));
+		} catch (failure) {
+			console.error(`could not report a failure: ${require_domain_fault_report.describeFault(failure)}`);
+		}
+	};
+	const reportStream = (error) => {
+		if (onFault !== void 0) require_domain_fault_report.deliverContained(async (suppressed) => onFault(error, void 0, suppressed), 0);
+	};
+	const iterator = source[Symbol.asyncIterator]();
+	let closing;
+	const close = () => {
+		closing ??= iterator.return?.().catch(reportStream);
+	};
+	signal?.addEventListener("abort", close, { once: true });
+	/** Takes and handles one item. Resolves true when there may be another, false when the stream ended or was stopped; rejects when the stream itself failed. */
+	async function step() {
+		if (signal?.aborted === true) return false;
+		const result = await iterator.next();
+		if (result.done === true) return false;
+		try {
+			await handle(result.value);
+		} catch (error) {
+			reportItem(error, result.value);
+		}
+		return true;
+	}
+	await new Promise((resolve) => {
+		const pump = () => {
+			step().then((more) => {
+				if (more) pump();
+				else resolve();
+			}, (error) => {
+				reportStream(error);
+				resolve();
+			});
+		};
+		pump();
+	});
+	signal?.removeEventListener("abort", close);
+	if (signal?.aborted === true) close();
+	await closing;
+}
+/** The refusal sent for a request whose handling failed before it was answered. It is a fixed code with no text from the failure, so a peer learns nothing of this side's internals; the code is this repository's convention for it, beside the codes a handler itself answers with. */
+const HANDLER_FAILED_OUTCOME = {
+	result: "error",
+	code: "internal-error"
+};
+/**
+* consumeEach for incoming manage-requests. A request whose handling fails before it was answered is answered with `internal-error`, so its sender is not left waiting for a response that will never come; if that answer cannot be sent either (the connection has gone), the request is dropped, and either way the failure is reported once. A request the handler already answered is not answered again.
+*/
+async function serveManageRequests(source, handle, options = {}) {
+	await consumeEach(source, async (incoming) => {
+		const state = { answered: false };
+		const tracked = {
+			...incoming,
+			respond: async (outcome) => {
+				state.answered = true;
+				await incoming.respond(outcome);
+			}
+		};
+		try {
+			await handle(tracked);
+		} catch (error) {
+			if (!state.answered) await incoming.respond(HANDLER_FAILED_OUTCOME).catch(() => void 0);
+			throw error;
+		}
+	}, {
+		...options,
+		sourceOf: options.sourceOf ?? ((incoming) => incoming.fromDevice === void 0 ? "" : require_domain_device_id.deviceIdToHex(incoming.fromDevice))
+	});
+}
+//#endregion
+exports.HANDLER_FAILED_OUTCOME = HANDLER_FAILED_OUTCOME;
+exports.consumeEach = consumeEach;
+exports.serveManageRequests = serveManageRequests;

package/dist/domain/consume-incoming.d.cts

@@ -0,0 +1,27 @@
+import { IncomingManageRequest, ManageOutcome } from "./mesh-session.cjs";
+//#region src/domain/consume-incoming.d.ts
+/** What a consumer is told about a failure. `item` is the item whose handling failed, or undefined when the stream itself failed. `suppressed` is how many failures from the same source were not reported before this report, not counting the one it carries (see FAULT_REPORT_INTERVAL_MS); it also counts failures of sources the reporter has stopped tracking. */
+export type ConsumeFault<T> = (error: unknown, item: T | undefined, suppressed: number) => void | Promise<void>;
+export interface ConsumeOptions<T> {
+  /** Told of a failure, at most once per source per FAULT_REPORT_INTERVAL_MS, so a peer cannot drive one report per failing item. A throw from this callback, or a promise it returns that rejects, is reported once to the console and dropped: reporting a fault never ends the loop either. Omit to drop failures silently. */
+  onFault?: ConsumeFault<T> | undefined;
+  /** Names the source an item's failure is counted against, so that one peer's failures do not hide another's. Items share one source when omitted. */
+  sourceOf?: ((item: T) => string) | undefined;
+  /** Stops the loop: the stream's iterator is closed when the signal aborts, and the loop ends at the next item boundary. See consumeEach for what that does to an item already taken. */
+  signal?: AbortSignal | undefined;
+  /** The clock the report interval is read from. */
+  now?: (() => number) | undefined;
+}
+/**
+ * Handles each item of `source` in order with `handle`. Resolves when the stream ends, fails or is stopped, and never rejects.
+ *
+ * Stopping with `signal` closes the stream's iterator at once and ends the loop at the next item boundary. An item the loop has already taken is handled to completion, never discarded, so a stream whose `return()` withdraws a pending wait (the session's own streams do) loses nothing to a later reader. A source whose `return()` cannot settle a pending `next()` (an async generator) ends the loop when that `next()` settles. A failure of the stream itself, or of closing it, is reported once and at once: it is not coalesced with item failures, because it ends the loop and no later report could carry it.
+ */
+export declare function consumeEach<T>(source: Readonly<AsyncIterable<T>>, handle: (item: T) => void | Promise<void>, options?: Readonly<ConsumeOptions<T>>): Promise<void>;
+/** The refusal sent for a request whose handling failed before it was answered. It is a fixed code with no text from the failure, so a peer learns nothing of this side's internals; the code is this repository's convention for it, beside the codes a handler itself answers with. */
+export declare const HANDLER_FAILED_OUTCOME: ManageOutcome;
+/**
+ * consumeEach for incoming manage-requests. A request whose handling fails before it was answered is answered with `internal-error`, so its sender is not left waiting for a response that will never come; if that answer cannot be sent either (the connection has gone), the request is dropped, and either way the failure is reported once. A request the handler already answered is not answered again.
+ */
+export declare function serveManageRequests(source: Readonly<AsyncIterable<IncomingManageRequest>>, handle: (incoming: IncomingManageRequest) => Promise<void>, options?: Readonly<ConsumeOptions<IncomingManageRequest>>): Promise<void>;
+//#endregion