@steve02081504/fount-p2p 0.0.22 → 0.0.24

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
+}

package/wire/part/group.mjs

@@ -0,0 +1,45 @@
+import { isPlainObject } from '../../core/object.mjs'
+
+import { attachPartWire } from './ingress.mjs'
+
+/** @typedef {import('../../wire/adapter.mjs').WireAdapter} WireAdapter */
+/** @typedef {import('../../wire/adapter.mjs').WireContext} WireContext */
+
+/**
+ * @param {unknown} data part 载荷
+ * @param {string} groupId 群 ID
+ * @returns {object | null} 校验通过后的载荷
+ */
+function parseGroupContext(data, groupId) {
+	if (!isPlainObject(data)) return null
+	if (data.groupId !== groupId) return null
+	return data
+}
+
+/**
+ * @param {WireAdapter} wire 底层适配器
+ * @param {string} groupId 群 ID
+ * @returns {WireAdapter['on']} 注入 groupId 的 on 包装
+ */
+function wrapWireOn(wire, groupId) {
+	return (name, handler) => wire.on(name, (data, peerId) => {
+		const payload = parseGroupContext(data, groupId)
+		if (!payload) return
+		handler(payload, peerId)
+	})
+}
+
+/**
+ * 群联邦房间挂载 part_wire（要求线载荷带 `groupId`）。
+ * @param {WireContext} wireContext 入站上下文
+ * @param {string} groupId 群 ID
+ * @param {WireAdapter} wire action 表
+ * @param {{ allowPartInvoke?: (payload: object) => boolean }} [options] 入站过滤
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachGroupPartWire(wireContext, groupId, wire, options = {}) {
+	return attachPartWire(wireContext, {
+		send: wire.send.bind(wire),
+		on: wrapWireOn(wire, groupId),
+	}, options)
+}

package/wire/{part_ingress.mjs → part/ingress.mjs}

@@ -1,34 +1,23 @@
+import { isPlainObject } from '../../core/object.mjs'
+import { parsePartpath } from '../../core/partpath.mjs'
+import { dispatchDeliveryInbound, dispatchRpcInbound } from '../../registries/inbound.mjs'
+import { subscribeWire } from '../subscribe.mjs'
 
-import { dispatchDeliveryInbound, dispatchRpcInbound } from '../registries/inbound.mjs'
-
-import { isPlainObject } from './ingress.mjs'
-import { buildPartInvokePayload } from './part_common.mjs'
 import {
 	isPartInvoke,
 	isPartInvokeResponse,
-	normalizePartpath,
 	unwrapPartInvokeResult,
-} from './part_invoke.mjs'
-
-/** @typedef {import('./part_invoke.mjs').PartInvokeResponse} PartInvokeResponse */
-
-/** @type {Map<string, { responses: PartInvokeResponse[], finish: () => void, maxResponses: number, respondedPeers: Set<string> }>} */
-export const pendingPartInvoke = new Map()
-
-/**
- * @typedef {{
- *   send: (name: string, payload: unknown, peerId: string | null) => void
- *   on: (name: string, handler: (payload: unknown, peerId: string) => void) => (() => void) | void
- * }} PartWireAdapter
- */
+} from './invoke.mjs'
+import { handleIncomingPartInvokeResponse } from './pending.mjs'
 
-/**
- * @typedef {{ replicaUsername?: string }} PartWireContext
- */
+/** @typedef {import('../../wire/adapter.mjs').WireAdapter} WireAdapter */
+/** @typedef {import('../../wire/adapter.mjs').WireContext} PartWireContext */
+/** @typedef {import('./invoke.mjs').PartInvokeResponse} PartInvokeResponse */
+/** @typedef {import('./invoke.mjs').PartInvoke} PartInvoke */
 
 /**
  * @param {object} data 入站 part_timeline_put 载荷
- * @param {string} partpath 已规范化 part 路径
+ * @param {string} partpath 已校验 part 路径
  * @returns {object | null} 白名单字段
  */
 function parsePartTimelinePut(data, partpath) {
@@ -44,25 +33,40 @@ function parsePartTimelinePut(data, partpath) {
 	}
 }
 
+/**
+ * @param {string} partpath part 路径
+ * @param {PartInvoke} invoke 调用体
+ * @param {string} [nodeHash] 来源节点
+ * @param {string} [groupId] 群上下文
+ * @returns {object} part_invoke 线载荷
+ */
+function buildPartInvokePayload(partpath, invoke, nodeHash, groupId) {
+	return {
+		partpath,
+		invoke,
+		...nodeHash ? { nodeHash } : {},
+		...groupId ? { groupId } : {},
+	}
+}
+
 /**
  * @param {PartWireContext} wireContext 入站上下文
- * @param {object} payload part_invoke 请求
+ * @param {object} payload part_invoke 请求（含已验证 peerId）
  * @returns {Promise<PartInvokeResponse | null>} RPC 处理器返回值
  */
 async function dispatchPartInvoke(wireContext, payload) {
-	const partpath = normalizePartpath(payload?.partpath)
+	const partpath = parsePartpath(payload?.partpath)
 	const invoke = payload?.invoke
 	if (!partpath || !isPlainObject(invoke)) return null
 	return dispatchRpcInbound({
 		replicaUsername: wireContext.replicaUsername,
-		requesterNodeHash: payload.nodeHash ? String(payload.nodeHash).trim() : null,
+		requesterNodeHash: payload.peerId ? String(payload.peerId).trim() : null,
 		groupId: payload.groupId ? String(payload.groupId).trim() : undefined,
 		peerId: payload.peerId,
 	}, {
 		type: 'part_invoke',
 		partpath,
 		invoke,
-		nodeHash: payload.nodeHash,
 		groupId: payload.groupId,
 		requestId: payload.requestId,
 	})
@@ -71,24 +75,32 @@ async function dispatchPartInvoke(wireContext, payload) {
 /**
  * 挂载 part_timeline_put / part_invoke / part_invoke_response。
  * @param {PartWireContext} wireContext 入站上下文
- * @param {PartWireAdapter} wire Trystero 适配器
+ * @param {WireAdapter} wire action 表
  * @param {{ allowPartInvoke?: (payload: object) => boolean }} [options] 入站过滤
  * @returns {() => void} 取消挂载的 dispose
  */
 export function attachPartWire(wireContext, wire, options = {}) {
-	const offs = [
-		wire.on('part_timeline_put', data => {
+	return subscribeWire(wire, {
+		/**
+		 * @param {unknown} data part_timeline_put 载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		part_timeline_put(data, peerId) {
 			if (!isPlainObject(data)) return
-			const partpath = normalizePartpath(data.partpath)
+			const partpath = parsePartpath(data.partpath)
 			if (!partpath) return
 			const message = parsePartTimelinePut(data, partpath)
 			if (!message) return
 			void dispatchDeliveryInbound({
 				replicaUsername: wireContext.replicaUsername,
-				requesterNodeHash: data.nodeHash ? String(data.nodeHash).trim() : null,
+				requesterNodeHash: peerId ? String(peerId).trim() : null,
 			}, message)
-		}),
-		wire.on('part_invoke', (data, peerId) => {
+		},
+		/**
+		 * @param {unknown} data part_invoke 载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		part_invoke(data, peerId) {
 			if (!isPlainObject(data)) return
 			if (options.allowPartInvoke?.(data) === false) return
 			const payload = { ...data, peerId }
@@ -96,27 +108,27 @@ export function attachPartWire(wireContext, wire, options = {}) {
 				void handleIncomingPartInvokeRequest(wireContext, payload, wire, peerId)
 			else
 				void handleIncomingPartInvokeFireAndForget(wireContext, payload, wire, peerId)
-		}),
-		wire.on('part_invoke_response', (data, peerId) => {
+		},
+		/**
+		 * @param {unknown} data part_invoke_response 载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		part_invoke_response(data, peerId) {
 			if (!isPlainObject(data)) return
 			handleIncomingPartInvokeResponse(data, peerId)
-		}),
-	]
-	return () => {
-		for (const off of offs)
-			try { off?.() } catch { /* ignore */ }
-	}
+		},
+	})
 }
 
 /**
  * @param {PartWireContext} wireContext 入站上下文
  * @param {object} payload part_invoke 请求（含 requestId）
- * @param {PartWireAdapter} wire 发送适配器
+ * @param {WireAdapter} wire 发送适配器
  * @param {string} peerId 对端
  * @returns {Promise<void>}
  */
 export async function handleIncomingPartInvokeRequest(wireContext, payload, wire, peerId) {
-	const partpath = normalizePartpath(payload?.partpath)
+	const partpath = parsePartpath(payload?.partpath)
 	if (!partpath || !payload.requestId) return
 
 	const response = await dispatchPartInvoke(wireContext, { ...payload, peerId })
@@ -135,40 +147,19 @@ export async function handleIncomingPartInvokeRequest(wireContext, payload, wire
 /**
  * @param {PartWireContext} wireContext 入站上下文
  * @param {object} payload part_invoke 请求（无 requestId）
- * @param {PartWireAdapter} wire 发送适配器
+ * @param {WireAdapter} wire 发送适配器
  * @param {string} peerId 对端
  * @returns {Promise<void>}
  */
 export async function handleIncomingPartInvokeFireAndForget(wireContext, payload, wire, peerId) {
-	const partpath = normalizePartpath(payload?.partpath)
+	const partpath = parsePartpath(payload?.partpath)
 	if (!partpath) return
 
 	const response = await dispatchPartInvoke(wireContext, { ...payload, peerId })
 	const followUp = unwrapPartInvokeResult(response)
 	if (!isPartInvoke(followUp)) return
 	try {
-		wire.send('part_invoke', buildPartInvokePayload({
-			partpath,
-			invoke: followUp,
-			nodeHash: payload.nodeHash,
-			groupId: payload.groupId,
-		}), peerId)
+		wire.send('part_invoke', buildPartInvokePayload(partpath, followUp, peerId, payload.groupId), peerId)
 	}
 	catch { /* disconnected */ }
 }
-
-/**
- * @param {object} payload 响应
- * @param {string} [peerId] Trystero 对端 id，用于同 peer 去重
- * @returns {void}
- */
-export function handleIncomingPartInvokeResponse(payload, peerId = '') {
-	const pending = pendingPartInvoke.get(payload.requestId)
-	if (!pending || !isPartInvokeResponse(payload.response)) return
-	if (peerId) {
-		if (pending.respondedPeers.has(peerId)) return
-		pending.respondedPeers.add(peerId)
-	}
-	pending.responses.push(payload.response)
-	if (pending.responses.length >= pending.maxResponses) pending.finish()
-}

package/wire/{part_invoke.mjs → part/invoke.mjs}

@@ -1,6 +1,4 @@
-import { isPlainObject } from './ingress.mjs'
-
-const PARTPATH_RE = /^[\w-]+(?:\/[\w-]+)*$/
+import { isPlainObject } from '../../core/object.mjs'
 
 /** @typedef {string} PartInvokeKind */
 
@@ -22,16 +20,6 @@ const PARTPATH_RE = /^[\w-]+(?:\/[\w-]+)*$/
 
 /** @typedef {PartInvokeResultResponse | PartInvokeErrorResponse} PartInvokeResponse */
 
-/**
- * @typedef {object} SocialRpcPartInvokeResponse
- * @property {object} result RPC 响应体
- */
-
-/**
- * @typedef {object} TimelinePutPartInvokeResponse
- * @property {{ ok: boolean }} result timeline ingest 结果
- */
-
 /**
  * @param {unknown} value 候选响应
  * @returns {value is PartInvokeResponse} 是否为 part_invoke 响应体
@@ -61,15 +49,6 @@ export function unwrapPartInvokeResult(response) {
 	return response.result ?? null
 }
 
-/**
- * @param {unknown} value partpath 字符串
- * @returns {string | null} 规范化 partpath
- */
-export function normalizePartpath(value) {
-	const path = String(value || '').trim().replace(/^\/+|\/+$/g, '')
-	return PARTPATH_RE.test(path) ? path : null
-}
-
 /**
  * @param {unknown} value invoke 体
  * @returns {value is PartInvoke} 是否含已知 kind

package/wire/part/pending.mjs

@@ -0,0 +1,32 @@
+import { isPartInvokeResponse } from './invoke.mjs'
+
+/** @typedef {import('./invoke.mjs').PartInvokeResponse} PartInvokeResponse */
+
+/**
+ * @typedef {{
+ *   responses: PartInvokeResponse[]
+ *   finish: () => void
+ *   maxResponses: number
+ *   respondedPeers: Set<string>
+ * }} PendingPartInvoke
+ */
+
+/** @type {Map<string, PendingPartInvoke>} */
+export const pendingPartInvoke = new Map()
+
+/**
+ * 入站 part_invoke_response：写入对应 pending 槽。
+ * @param {object} payload 响应
+ * @param {string} [peerId] 对端 id，用于同 peer 去重
+ * @returns {void}
+ */
+export function handleIncomingPartInvokeResponse(payload, peerId = '') {
+	const pending = pendingPartInvoke.get(payload.requestId)
+	if (!pending || !isPartInvokeResponse(payload.response)) return
+	if (peerId) {
+		if (pending.respondedPeers.has(peerId)) return
+		pending.respondedPeers.add(peerId)
+	}
+	pending.responses.push(payload.response)
+	if (pending.responses.length >= pending.maxResponses) pending.finish()
+}

package/wire/part/query.mjs

@@ -0,0 +1,91 @@
+import {
+	handleIncomingPartQueryResponse,
+	processIncomingPartQueryRequest,
+	queryNetwork as queryNetworkCore,
+	resolvePartQueryState,
+} from '../../federation/part_query/runtime.mjs'
+import {
+	parsePartQueryReq,
+	parsePartQueryRes,
+} from '../../schemas/part_query.mjs'
+import partQueryTunables from '../../schemas/part_query.tunables.json' with { type: 'json' }
+import { sendToNodeLink } from '../../transport/link_registry.mjs'
+import { consumeWireRateBucket } from '../rate_bucket.mjs'
+import { subscribeWire } from '../subscribe.mjs'
+
+/** @typedef {import('../adapter.mjs').WireAdapter} WireAdapter */
+/** @typedef {import('../adapter.mjs').WireContext} WireContext */
+/** @typedef {import('../../federation/part_query/runtime.mjs').PartQueryDependencies} PartQueryDependencies */
+
+/**
+ * @param {PartQueryDependencies} [dependencies] 可注入依赖
+ * @returns {PartQueryDependencies} 补上默认 deliver 后的依赖
+ */
+function withDefaultDeliver(dependencies = {}) {
+	return {
+		...dependencies,
+		deliver: dependencies.deliver || ((nodeHash, action, payload) =>
+			sendToNodeLink(nodeHash, { scope: 'node', action, payload })),
+	}
+}
+
+/**
+ * 挂载 part_query_req / part_query_res（入站 parse / dedupe / rate；运行时在 federation）。
+ * @param {WireContext} wireContext 入站上下文
+ * @param {WireAdapter} wire wire
+ * @param {PartQueryDependencies} [dependencies] 可注入依赖（含 per-node state）
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachPartQueryWire(wireContext, wire, dependencies = {}) {
+	const deps = withDefaultDeliver(dependencies)
+	const state = resolvePartQueryState(deps)
+	return subscribeWire(wire, {
+		/**
+		 * @param {unknown} data part_query_req 载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		part_query_req(data, peerId) {
+			const request = parsePartQueryReq(data)
+			if (!request) return
+			if (!state.takeDedupe(request.requestId)) return
+			const source = String(peerId || request.originNodeHash || '').trim().toLowerCase()
+			if (source && !consumeWireRateBucket(`part_query:${source}`, {
+				maxCount: partQueryTunables.ratePerSourcePerMin,
+			})) return
+			void processIncomingPartQueryRequest(wireContext, wire, request, String(peerId || ''), deps)
+		},
+		/**
+		 * @param {unknown} data part_query_res 载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		part_query_res(data, peerId) {
+			const response = parsePartQueryRes(data)
+			if (!response) return
+			handleIncomingPartQueryResponse(response, String(peerId || ''), deps)
+		},
+	})
+}
+
+/**
+ * 多跳查询（默认经 link_registry 投递；可注入 deliver）。
+ * @param {string} username trust graph 上下文
+ * @param {string} partpath part 路径
+ * @param {string} kind 查询标签
+ * @param {unknown} query 不透明查询
+ * @param {Parameters<typeof queryNetworkCore>[4]} [options] 选项
+ * @returns {Promise<unknown[]>} 合并后的 rows
+ */
+export function queryNetwork(username, partpath, kind, query, options = {}) {
+	return queryNetworkCore(username, partpath, kind, query, withDefaultDeliver(options))
+}
+
+/**
+ * Part query 运行时（state、入站 handler、hop timeout、测试重置）。
+ */
+export {
+	createPartQueryNodeState,
+	registerQueryInboundHandler,
+	resetPartQueryStateForTests,
+	resolvePartQueryHopTimeoutMs,
+	resolvePartQueryState,
+} from '../../federation/part_query/runtime.mjs'

package/wire/subscribe.mjs

@@ -0,0 +1,13 @@
+/**
+ * 批量注册 wire action，返回统一 dispose。
+ * @param {import('./adapter.mjs').WireAdapter} wire action 表
+ * @param {Record<string, (payload: unknown, peerId: string) => void>} handlers action → handler
+ * @returns {() => void} 取消全部注册
+ */
+export function subscribeWire(wire, handlers) {
+	const disposers = Object.entries(handlers).map(([name, handler]) => wire.on(name, handler))
+	return () => {
+		for (const dispose of disposers)
+			dispose()
+	}
+}