@steve02081504/fount-p2p 0.0.23 → 0.0.25

package/transport/node_scope/features.mjs

@@ -0,0 +1,166 @@
+import { attachNodeScopeFedResponder } from '../../files/fed/responder.mjs'
+import { attachMailboxWire } from '../../mailbox/wire.mjs'
+import { attachPartWire } from '../../wire/part/ingress.mjs'
+import { attachPartQueryWire } from '../../wire/part/query.mjs'
+
+import {
+	clearNodeScopeSubscribe,
+	ensureNodeScope,
+	getNodeScopeContext,
+	getNodeScopeWire,
+} from './wire.mjs'
+
+/** @typedef {import('./wire.mjs').NodeScopeWire} NodeScopeWire */
+/** @typedef {import('./wire.mjs').NodeScopeContext} NodeScopeContext */
+
+/** @type {Set<() => void>} */
+const nodeScopeFeatureDisposers = new Set()
+
+/** @type {Map<string, { count: number, disposeCore: () => void }>} */
+const featureAttachRefs = new Map()
+
+/**
+ * @param {() => void} dispose - feature 卸载函数
+ * @returns {() => void} 包装后的 dispose（同时从跟踪集移除）
+ */
+function trackFeatureDisposer(dispose) {
+	nodeScopeFeatureDisposers.add(dispose)
+	return () => {
+		dispose()
+		nodeScopeFeatureDisposers.delete(dispose)
+	}
+}
+
+/**
+ * 同一 feature 多次 attach 共享一份 wire；dispose 引用计数归零才卸。
+ * @param {string} key - feature 去重键
+ * @param {() => () => void} attachCore - 首次 attach 时执行，返回核心 dispose
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+function attachFeatureRefCounted(key, attachCore) {
+	let entry = featureAttachRefs.get(key)
+	if (!entry) {
+		entry = { count: 0, disposeCore: attachCore() }
+		featureAttachRefs.set(key, entry)
+	}
+	entry.count++
+	return trackFeatureDisposer(() => {
+		const current = featureAttachRefs.get(key)
+		if (!current) return
+		current.count--
+		if (current.count > 0) return
+		current.disposeCore()
+		featureAttachRefs.delete(key)
+	})
+}
+
+/**
+ * @param {string} key - feature 去重键
+ * @param {(wire: NodeScopeWire, context: NodeScopeContext) => () => void} attachCore - 首次 attach
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+export function attachNodeScopeFeature(key, attachCore, options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted(key, () => attachCore(getNodeScopeWire(), getNodeScopeContext()))
+}
+
+/** @type {Record<string, (wire: NodeScopeWire, context: NodeScopeContext) => () => void>} */
+const builtinFeatures = {
+	/**
+	 * @param {NodeScopeWire} wire node scope wire
+	 * @param {NodeScopeContext} context 入站上下文
+	 * @returns {() => void} 取消挂载的 dispose
+	 */
+	mailbox: (wire, context) => attachMailboxWire(context, wire),
+	/**
+	 * @param {NodeScopeWire} wire node scope wire
+	 * @param {NodeScopeContext} context 入站上下文
+	 * @returns {() => void} 取消挂载的 dispose
+	 */
+	part: (wire, context) => attachPartWire(context, wire),
+	/**
+	 * @param {NodeScopeWire} wire node scope wire
+	 * @param {NodeScopeContext} context 入站上下文
+	 * @returns {() => void} 取消挂载的 dispose
+	 */
+	partQuery: (wire, context) => attachPartQueryWire(context, wire),
+	/**
+	 * @param {NodeScopeWire} wire node scope wire
+	 * @returns {() => void} 取消挂载的 dispose
+	 */
+	chunks: wire => attachNodeScopeFedResponder(wire),
+}
+
+/**
+ * @param {keyof typeof builtinFeatures} key - 内置 feature 名
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+function attachBuiltin(key, options = {}) {
+	return attachNodeScopeFeature(key, builtinFeatures[key], options)
+}
+
+/**
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeMailbox(options = {}) {
+	return attachBuiltin('mailbox', options)
+}
+
+/**
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopePart(options = {}) {
+	return attachBuiltin('part', options)
+}
+
+/**
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopePartQuery(options = {}) {
+	return attachBuiltin('partQuery', options)
+}
+
+/**
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeChunks(options = {}) {
+	return attachBuiltin('chunks', options)
+}
+
+/**
+ * 全业务 preset（part / partQuery / mailbox / chunks）。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消全部 preset 挂载的 dispose
+ */
+export function attachNodeScopeDefaultFeatures(options = {}) {
+	const disposers = [
+		attachNodeScopePart(options),
+		attachNodeScopePartQuery(options),
+		attachNodeScopeMailbox(options),
+		attachNodeScopeChunks(options),
+	]
+	return () => {
+		for (const dispose of disposers) dispose()
+	}
+}
+
+/**
+ * 卸掉 feature 挂载；可选保留 node scope 订阅。
+ * @param {{ keepSubscribe?: boolean }} [options] - true 时保留 node scope 订阅
+ * @returns {void}
+ */
+export function stopNodeScopeRuntime(options = {}) {
+	for (const dispose of [...nodeScopeFeatureDisposers]) dispose()
+	nodeScopeFeatureDisposers.clear()
+	for (const entry of featureAttachRefs.values())
+		try { entry.disposeCore() } catch { /* ignore */ }
+	featureAttachRefs.clear()
+	if (options.keepSubscribe) return
+	clearNodeScopeSubscribe()
+}

package/transport/node_scope/wire.mjs

@@ -0,0 +1,143 @@
+import { subscribeScope, sendToNodeLink } from '../link_registry.mjs'
+
+/** @typedef {import('../../wire/adapter.mjs').WireAdapter} NodeScopeWire */
+/** @typedef {{ replicaUsername: string }} NodeScopeContext */
+
+/** @type {Map<string, Set<(payload: unknown, peerId: string) => void>>} */
+const nodeActionHandlers = new Map()
+
+/** @type {Set<(context: NodeScopeContext, wire: NodeScopeWire) => void>} */
+const nodeScopeWireHooks = new Set()
+
+/** @type {NodeScopeContext} */
+const nodeScopeContext = { replicaUsername: '' }
+
+/** @type {NodeScopeWire | null} */
+let nodeScopeWire = null
+
+/** @type {(() => void) | null} */
+let nodeScopeSubscribeCleanup = null
+
+/**
+ * @returns {NodeScopeWire} node scope 的 wire 适配器
+ */
+function createNodeScopeWire() {
+	return {
+		/**
+		 * @param {string} name action 名
+		 * @param {(payload: unknown, peerId: string) => void} handler 回调
+		 * @returns {() => void} 取消订阅
+		 */
+		on(name, handler) {
+			if (!nodeActionHandlers.has(name)) nodeActionHandlers.set(name, new Set())
+			nodeActionHandlers.get(name).add(handler)
+			return () => {
+				const set = nodeActionHandlers.get(name)
+				if (!set) return
+				set.delete(handler)
+				if (!set.size) nodeActionHandlers.delete(name)
+			}
+		},
+		/**
+		 * @param {string} name action 名
+		 * @param {unknown} payload 载荷
+		 * @param {string} peerId 目标 peer
+		 * @returns {void}
+		 */
+		send(name, payload, peerId) {
+			if (!peerId) return
+			void sendToNodeLink(peerId, { scope: 'node', action: name, payload }).catch(() => { })
+		},
+	}
+}
+
+/**
+ * @param {string} action - action 名
+ * @returns {boolean} 是否已挂载处理器
+ */
+export function hasNodeScopeAction(action) {
+	return (nodeActionHandlers.get(action)?.size ?? 0) > 0
+}
+
+/**
+ * @param {string} action - action 名
+ * @returns {number} 已注册的处理器数量
+ */
+export function countNodeScopeActionHandlers(action) {
+	return nodeActionHandlers.get(action)?.size ?? 0
+}
+
+/**
+ * 测试/调试：直接派发已挂载的 node action。
+ * @param {string} action - action 名
+ * @param {unknown} payload - 载荷
+ * @param {string} peerId - 发送方 nodeHash
+ * @returns {boolean} 是否有处理器被调用
+ */
+export function dispatchNodeScopeAction(action, payload, peerId) {
+	const handlers = nodeActionHandlers.get(action)
+	if (!handlers?.size) return false
+	for (const handler of handlers)
+		try { handler(payload, peerId) } catch { /* ignore */ }
+	return true
+}
+
+/**
+ * @returns {NodeScopeWire | null} 当前 wire，未 ensure 时为 null
+ */
+export function getNodeScopeWire() {
+	return nodeScopeWire
+}
+
+/**
+ * @returns {NodeScopeContext} 可变 node scope 上下文
+ */
+export function getNodeScopeContext() {
+	return nodeScopeContext
+}
+
+/**
+ * 只订阅 node scope 派发，不挂任何 feature。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消订阅的 dispose
+ */
+export function ensureNodeScope(options = {}) {
+	if (options.replicaUsername != null)
+		nodeScopeContext.replicaUsername = String(options.replicaUsername)
+	if (nodeScopeSubscribeCleanup) return nodeScopeSubscribeCleanup
+	nodeScopeSubscribeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
+		const handlers = nodeActionHandlers.get(envelope.action)
+		if (!handlers?.size) return
+		for (const handler of handlers)
+			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
+	})
+	if (!nodeScopeWire) {
+		nodeScopeWire = createNodeScopeWire()
+		for (const hook of nodeScopeWireHooks)
+			try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	}
+	return nodeScopeSubscribeCleanup
+}
+
+/**
+ * 在 node scope wire 创建时（或已存在时立即）回调；shell 用此挂自定义 action。
+ * @param {(context: NodeScopeContext, wire: NodeScopeWire) => void} hook - wire 就绪回调
+ * @returns {() => void} 取消注册的 dispose
+ */
+export function registerNodeScopeWireHook(hook) {
+	nodeScopeWireHooks.add(hook)
+	if (nodeScopeWire)
+		try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	return () => nodeScopeWireHooks.delete(hook)
+}
+
+/**
+ * 卸掉 scope 订阅与 wire（feature 须先卸）。
+ * @returns {void}
+ */
+export function clearNodeScopeSubscribe() {
+	nodeScopeSubscribeCleanup?.()
+	nodeScopeSubscribeCleanup = null
+	nodeScopeWire = null
+	nodeActionHandlers.clear()
+}

package/transport/remote_user_room.mjs

@@ -28,7 +28,6 @@ registerFederationRoomProvider('remote-user-room', () => {
  * @returns {Promise<RemoteUserRoomSlot>} 房间槽
  */
 export async function ensureRemoteUserRoom(username, targetNodeHash) {
-	void username
 	const key = targetNodeHash.toLowerCase()
 	const existing = slots.get(key)
 	if (existing) return existing

package/{rooms → transport}/scoped_link.mjs

@@ -1,4 +1,4 @@
-import { createGroupLinkSet } from '../transport/group_link_set.mjs'
+import { createGroupLinkSet } from './group_link_set.mjs'
 
 /**
  * scoped 房间：group_link_set 的薄预设（任意 scope + allowNode + 发现即拨）。

package/transport/user_room.mjs

@@ -5,21 +5,12 @@ import { registerFederationRoomProvider } from '../registries/room_provider.mjs'
 import { shuffleInPlace } from '../utils/shuffle.mjs'
 
 import { getLinkRegistry, listLinks, sendToNodeLink } from './link_registry.mjs'
-import {
-	attachUserRoomDefaultWires,
-	ensureNodeScope,
-} from './node_scope.mjs'
+import { attachNodeScopeDefaultFeatures } from './node_scope/features.mjs'
+import { ensureNodeScope } from './node_scope/wire.mjs'
 import { USER_ROOM_SCOPE } from './room_scopes.mjs'
 
-/**
- * 经 node scope 向对端发 action。
- * @param {string} peerId 对端 nodeHash
- * @param {string} action 动作名
- * @param {unknown} payload 载荷
- * @returns {Promise<boolean>} 是否发出
- */
-const sendNodeAction = (peerId, action, payload) =>
-	sendToNodeLink(peerId, { scope: 'node', action, payload })
+/** User Room 随机 peer 转发默认上限 */
+const USER_ROOM_PEER_FANOUT_DEFAULT = 6
 
 /** @type {Promise<UserRoomSlot> | null} */
 let userRoomInflight = null
@@ -50,7 +41,7 @@ export function activeLinkRoster() {
  *   roomId: string
  *   roomSecret: string
  *   room: object | null
- *   sendToPeer: (peerId: string, actionName: string, payload: unknown) => void
+ *   sendToPeer: (peerId: string, actionName: string, payload: unknown) => Promise<boolean>
  *   getRoster: () => Array<{ peerId: string, remoteNodeHash: string | undefined }>
  *   getPeerIdByNodeHash: (nodeHash: string) => string | null
  * }} UserRoomSlot
@@ -74,7 +65,7 @@ registerFederationRoomProvider('user-room', () => {
 		 * @param {string} peerId - 目标 peer
 		 * @param {string} actionName - node scope action 名
 		 * @param {unknown} payload - 载荷
-		 * @returns {void}
+		 * @returns {Promise<boolean>} 是否发出
 		 */
 		sendToPeer: (peerId, actionName, payload) => slot.sendToPeer(peerId, actionName, payload),
 	}]
@@ -95,7 +86,7 @@ export function resolveUserRoomCredentials() {
 }
 
 /**
- * 用户房间槽 + runtime；默认不挂业务 wire（用 `attachUserRoomDefaultWires` / `attachDefaultWires: true`）。
+ * 用户房间槽 + runtime；默认不挂业务 wire（用 `attachNodeScopeDefaultFeatures` / `attachDefaultWires: true`）。
  * @param {{ replicaUsername?: string, attachDefaultWires?: boolean }} [options] - 副本用户名与是否挂载默认 wire
  * @returns {Promise<UserRoomSlot>} 用户房间槽
  */
@@ -105,7 +96,7 @@ export async function ensureUserRoom(options = {}) {
 		ensureNodeScope({ replicaUsername: options.replicaUsername })
 	if (userRoomSlot) {
 		if (attachDefaultWires && !userRoomDefaultWiresDispose)
-			userRoomDefaultWiresDispose = attachUserRoomDefaultWires({ replicaUsername: options.replicaUsername })
+			userRoomDefaultWiresDispose = attachNodeScopeDefaultFeatures({ replicaUsername: options.replicaUsername })
 		return userRoomSlot
 	}
 	if (userRoomInflight) return await userRoomInflight
@@ -115,7 +106,7 @@ export async function ensureUserRoom(options = {}) {
 		await getLinkRegistry().ensureRuntime()
 		ensureNodeScope({ replicaUsername: options.replicaUsername })
 		if (attachDefaultWires && !userRoomDefaultWiresDispose)
-			userRoomDefaultWiresDispose = attachUserRoomDefaultWires({ replicaUsername: options.replicaUsername })
+			userRoomDefaultWiresDispose = attachNodeScopeDefaultFeatures({ replicaUsername: options.replicaUsername })
 		const creds = resolveUserRoomCredentials()
 		userRoomSlot = {
 			roomId: creds.roomId,
@@ -125,10 +116,10 @@ export async function ensureUserRoom(options = {}) {
 			 * @param {string} peerId - 目标 peer
 			 * @param {string} actionName - node scope action 名
 			 * @param {unknown} payload - 载荷
-			 * @returns {void}
+			 * @returns {Promise<boolean>} 是否发出
 			 */
 			sendToPeer(peerId, actionName, payload) {
-				void sendNodeAction(peerId, actionName, payload).catch(() => { })
+				return sendToNodeLink(peerId, { scope: 'node', action: actionName, payload }).catch(() => false)
 			},
 			/**
 			 * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 当前活跃链路 roster
@@ -162,16 +153,15 @@ export async function ensureUserRoom(options = {}) {
  * @returns {Promise<number>} 成功转发的 peer 数
  */
 export async function deliverToUserRoomPeers(username, actionName, payload, exceptPeerId = null, limit) {
-	void username
-	const { USER_ROOM_PEER_FANOUT_DEFAULT } = await import('../wire/part_common.mjs')
 	const fanoutLimit = limit ?? USER_ROOM_PEER_FANOUT_DEFAULT
-	const body = { ...payload, nodeHash: getNodeHash() }
+	if (fanoutLimit <= 0) return 0
+	const slot = await ensureUserRoom({ replicaUsername: username })
 	let sent = 0
-	const peers = shuffleInPlace(activeLinkRoster()
+	const peers = shuffleInPlace(slot.getRoster()
 		.filter(({ peerId }) => peerId && peerId !== exceptPeerId))
 	for (const { peerId } of peers)
 		try {
-			if (await sendNodeAction(peerId, actionName, body))
+			if (await slot.sendToPeer(peerId, actionName, { ...payload, nodeHash: getNodeHash() }))
 				sent++
 			if (sent >= fanoutLimit) break
 		}
@@ -179,6 +169,3 @@ export async function deliverToUserRoomPeers(username, actionName, payload, exce
 
 	return sent
 }
-
-/** 再导出：node-scope 订阅与默认 wires（见 `node_scope.mjs`）。 */
-export { attachUserRoomDefaultWires, ensureNodeScope } from './node_scope.mjs'

package/utils/fetch_wait.mjs

@@ -0,0 +1,98 @@
+/**
+ * 有界 pending fetch 等待表（chunk / manifest 等入站响应槽）。
+ * @template T
+ * @param {{ maxSize: number }} options 容量
+ * @returns {{
+ *   pending: Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } }>,
+ *   register: (key: string, expectedKey: string, timeoutMs: number, options?: { rejectOnTimeout?: boolean }) => { done: Promise<T | null>, cancel: () => void },
+ *   peek: (key: string) => { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } } | undefined,
+ *   settle: (key: string, value: T | null | Error) => boolean,
+ * }} 等待表 API
+ */
+export function createFetchWaitTable({ maxSize }) {
+	/** @type {Map<string, { expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } }>} */
+	const pending = new Map()
+
+	/**
+	 * @param {string} key 等待键
+	 * @param {T | null | Error} value 结果或错误
+	 * @returns {boolean} 是否命中并完成
+	 */
+	function settle(key, value) {
+		const entry = pending.get(key)
+		if (!entry) return false
+		clearTimeout(entry.timer)
+		pending.delete(key)
+		entry.finish(value)
+		return true
+	}
+
+	return {
+		pending,
+
+		/**
+		 * @param {string} key 唯一等待键
+		 * @param {string} expectedKey 期望匹配键
+		 * @param {number} timeoutMs 超时
+		 * @param {{ rejectOnTimeout?: boolean }} [options] 超时是否 reject
+		 * @returns {{ done: Promise<T | null>, cancel: () => void }} 等待句柄
+		 */
+		register(key, expectedKey, timeoutMs, options = {}) {
+			if (!key)
+				return {
+					done: Promise.resolve(null),
+					/** @returns {void} */
+					cancel: () => { },
+				}
+
+			const existing = pending.get(key)
+			if (existing) return existing.handle
+
+			if (pending.size >= maxSize)
+				return {
+					done: Promise.resolve(null),
+					/** @returns {void} */
+					cancel: () => { },
+				}
+
+			/** @type {(value: T | null | Error) => void} */
+			let finish
+			const done = new Promise((resolve, reject) => {
+				/**
+				 * @param {T | null | Error} value 完成值或错误
+				 * @returns {void}
+				 */
+				finish = value => {
+					if (value instanceof Error) reject(value)
+					else resolve(value)
+				}
+			})
+
+			const timer = setTimeout(() => {
+				pending.delete(key)
+				if (options.rejectOnTimeout) finish(new Error('fetch timeout'))
+				else finish(null)
+			}, timeoutMs)
+
+			/** @type {{ done: Promise<T | null>, cancel: () => void }} */
+			const handle = {
+				done,
+				/** @returns {void} 取消等待 */
+				cancel: () => settle(key, null),
+			}
+			pending.set(key, { expectedKey, timer, finish, handle })
+			return handle
+		},
+
+		/**
+		 * 只读查看，不移除。
+		 * @param {string} key 等待键
+		 * @returns {{ expectedKey: string, timer: ReturnType<typeof setTimeout>, finish: (value: T | null | Error) => void, handle: { done: Promise<T | null>, cancel: () => void } } | undefined} 等待条目
+		 */
+		peek(key) {
+			return pending.get(key)
+		},
+
+		settle,
+	}
+}

package/wire/adapter.mjs

@@ -0,0 +1,13 @@
+/**
+ * @typedef {{
+ *   on: (name: string, handler: (payload: unknown, peerId: string) => void) => (() => void) | void
+ *   send: (name: string, payload: unknown, peerId: string | null) => void
+ * }} WireAdapter
+ */
+
+/**
+ * @typedef {{ replicaUsername?: string }} WireContext
+ */
+
+/** Wire 适配器与上下文的类型导出（运行时代码见各 wire 模块）。 */
+export {}

package/wire/ingress.mjs

@@ -4,14 +4,7 @@
 import { Buffer } from 'node:buffer'
 
 import { isHex64, isSignatureHex128 } from '../core/hexIds.mjs'
-
-/**
- * @param {unknown} value 待判定值
- * @returns {value is Record<string, unknown>} 是否为非 null 的普通对象（非数组）
- */
-export function isPlainObject(value) {
-	return value != null && !Array.isArray(value) && typeof value === 'object'
-}
+import { isPlainObject } from '../core/object.mjs'
 
 /**
  * 解析 WebSocket / Trystero 入站 JSON 帧。

package/wire/part/fanout.mjs

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+
+import { getNodeHash } from '../../node/identity.mjs'
+import { DEFAULT_TRUST_GRAPH_OWNER, requireTrustGraphProvider } from '../../trust_graph/registry.mjs'
+
+import { unwrapPartInvokeResult } from './invoke.mjs'
+import { pendingPartInvoke } from './pending.mjs'
+
+/** @typedef {import('./invoke.mjs').PartInvokeResponse} PartInvokeResponse */
+/** @typedef {import('./invoke.mjs').PartInvoke} PartInvoke */
+
+/** 时间线 part_timeline_put fanout 上限 */
+export const TIMELINE_FANOUT_LIMIT = 8
+/** part_invoke RPC collect 默认响应数 */
+export const PART_INVOKE_FANOUT_DEFAULT = 6
+
+/**
+ * @param {string} partpath part 路径
+ * @param {PartInvoke} invoke 调用体
+ * @param {string} [nodeHash] 来源节点
+ * @param {string} [requestId] RPC 请求 id
+ * @returns {object} part_invoke 线载荷
+ */
+function buildPartInvokePayload(partpath, invoke, nodeHash, requestId) {
+	return {
+		partpath,
+		invoke,
+		...nodeHash ? { nodeHash } : {},
+		...requestId ? { requestId } : {},
+	}
+}
+
+/**
+ * @param {PartInvokeResponse[]} results collect 原始结果
+ * @returns {object[]} 仅含成功 result 的载荷
+ */
+export function partInvokeDataRows(results) {
+	/** @type {object[]} */
+	const rows = []
+	for (const row of results) {
+		const data = unwrapPartInvokeResult(row)
+		if (data != null) rows.push(/** @type {object} */ data)
+	}
+	return rows
+}
+
+/**
+ * @param {PartInvokeResponse[]} results collect 原始结果
+ * @returns {string[]} 邻居返回的错误信息
+ */
+export function partInvokeErrorMessages(results) {
+	/** @type {string[]} */
+	const errors = []
+	for (const row of results) {
+		const message = row?.error?.message
+		if (message) errors.push(message)
+	}
+	return errors
+}
+
+/**
+ * 向 trust-graph top-K 扇出 part_invoke，收集 part_invoke_response。
+ * 调用方须已挂载 `attachPartWire`（否则收不到 response）。
+ * @param {string} username trust graph 上下文
+ * @param {string} partpath part 路径
+ * @param {PartInvoke} invoke 调用体
+ * @param {number} [timeoutMs=2500] 超时
+ * @param {number} [maxResponses=6] 最多响应数
+ * @returns {Promise<PartInvokeResponse[]>} 邻居 PartInvokeResponse（含 error）
+ */
+export async function collectPartInvokeResponses(username, partpath, invoke, timeoutMs = 2500, maxResponses = PART_INVOKE_FANOUT_DEFAULT) {
+	const requestId = randomUUID()
+	const nodeHash = getNodeHash()
+	/** @type {PartInvokeResponse[]} */
+	const responses = []
+
+	const waitForResponses = new Promise(resolve => {
+		/** 超时或收满响应后清理 pending 并完成 Promise。 */
+		const finish = () => {
+			clearTimeout(timer)
+			pendingPartInvoke.delete(requestId)
+			resolve(responses)
+		}
+		const timer = setTimeout(finish, timeoutMs)
+		pendingPartInvoke.set(requestId, { responses, finish, maxResponses, respondedPeers: new Set() })
+	})
+
+	const sent = await requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER).fanoutToTopNodes(
+		username,
+		'part_invoke',
+		buildPartInvokePayload(partpath, invoke, nodeHash, requestId),
+		maxResponses,
+	)
+
+	const pending = pendingPartInvoke.get(requestId)
+	if (pending && sent === 0) pending.finish()
+
+	return waitForResponses
+}