@steve02081504/fount-p2p 0.0.28 → 0.0.30

package/discovery/bt/index.mjs

@@ -297,9 +297,7 @@ export function createBluetoothDiscoveryProvider() {
 				cleanup()
 				reject(new Error('p2p: bt signal peripheral timeout'))
 			}, 8_000)
-			/**
-			 * @returns {void}
-			 */
+			/** 清理信号超时计时器并移除 discover 监听器 */
 			function cleanup() {
 				clearTimeout(deadline)
 				noble.removeListener('discover', onDiscover)

package/discovery/nostr.mjs

@@ -34,6 +34,8 @@ export const NOSTR_CLOSE_GRACE_MS = 1_000
 export const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
 /** 共享 relay 会话断线后重连间隔。 */
 export const NOSTR_RECONNECT_DELAY_MS = 500
+/** 无 sub/publish 工作时共享 relay 空闲回收延迟（给连续 send 复用窗口）。 */
+export const NOSTR_IDLE_DROP_MS = 2_000
 
 /** Nostr network advert 事件 kind（addressable，可存储）。 */
 export const NOSTR_ADVERT_KIND = 30787
@@ -241,6 +243,7 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
 			reject(error)
 		}
 		/**
+		 * 收到 abort 信号时失败
 		 * @returns {void}
 		 */
 		const onAbort = () => fail(new Error('nostr: aborted'))
@@ -265,9 +268,10 @@ function connectRelay(relayUrl, timeoutMs = NOSTR_CONNECT_TIMEOUT_MS, signal) {
  * @param {string} relayUrl 中继 URL
  * @param {object} event 待发布事件
  * @param {AbortSignal} [signal] 取消信号
+ * @param {() => boolean} [isCurrent] 该尝试是否仍是 publishRequest 的当前尝试（断线重发后过期）
  * @returns {Promise<boolean>} relay 是否接受 EVENT
  */
-function publishEventOnRelay(ws, relayUrl, event, signal) {
+function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
 	return new Promise((resolve, reject) => {
 		if (signal?.aborted) {
 			reject(new Error('nostr: aborted'))
@@ -285,10 +289,13 @@ function publishEventOnRelay(ws, relayUrl, event, signal) {
 			clearTimeout(timer)
 			signal?.removeEventListener('abort', onAbort)
 			ws.off('message', onMessage)
+			// 过期的 in-flight 尝试：只清理自身监听器/定时器，不结算，避免影响重发后的当前尝试。
+			if (!isCurrent()) return
 			if (error) reject(error)
 			else resolve(ok)
 		}
 		/**
+		 * 收到 abort 信号时以失败结束
 		 * @returns {void}
 		 */
 		const onAbort = () => finish(false, new Error('nostr: aborted'))
@@ -331,42 +338,93 @@ function publishEventOnRelay(ws, relayUrl, event, signal) {
  * @returns {Promise<void>}
  */
 async function publishEvent(relayUrls, event, signal) {
-	if (!relayUrls.length) throw new Error('nostr: no relay')
+	const urls = dedupeRelayUrls(relayUrls)
+	if (!urls.length) throw new Error('nostr: no relay')
 	let published = false
 	let lastError = null
-	await Promise.allSettled(relayUrls.map(async relayUrl => {
-		if (signal?.aborted) throw new Error('nostr: aborted')
-		const ws = await connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS, signal)
+	await Promise.allSettled(urls.map(async relayUrl => {
 		try {
-			if (signal?.aborted) throw new Error('nostr: aborted')
-			const ok = await publishEventOnRelay(ws, relayUrl, event, signal)
-			if (ok) published = true
+			if (await publishViaSharedRelay(relayUrl, event, signal)) published = true
 		}
 		catch (error) {
 			lastError = error
-			throw error
-		}
-		finally {
-			dropWebSocket(ws)
 		}
 	}))
 	if (!published) throw lastError || new Error('nostr: no relay accepted publish')
 }
 
 /**
- * 共享 relay 会话：多 SUB 复用同一 URL 的 WebSocket，避免 signal/presence/advert 各建一池。
- * 仍有活跃 sub 时断线会自动重连并重发 REQ。
+ * 一次共享 relay publish 请求：入队（pending）与已派发（inflight）时共用同一结构。
+ * attempt 标识每次实际发送尝试，断线重发会递增；旧的 in-flight 尝试据此自检为过期后自我清理，
+ * 不再结算当前尝试。
+ * @typedef {{
+ *   event: object,
+ *   signal: AbortSignal | undefined,
+ *   attempt: number,
+ *   onAbort: (() => void) | null,
+ *   removeAbort: (() => void) | null,
+ *   resolve: (ok: boolean) => void,
+ *   reject: (err: Error) => void,
+ * }} NostrPublishRequest
+ */
+
+/**
+ * 共享 relay 会话：多 SUB / publish 复用同一 URL 的 WebSocket，避免 signal/presence/advert 各建一池、
+ * 以及每次 send 重开一条连接（内存泄漏）。
+ * 仍有活跃 sub 或待发 publish 时断线会自动重连并重发 REQ / 重发 EVENT。
  * @typedef {{
  *   ws: import('ws').WebSocket | null,
  *   connecting: boolean,
  *   reconnectTimer: ReturnType<typeof setTimeout> | null,
+ *   idleTimer: ReturnType<typeof setTimeout> | null,
  *   subs: Map<string, { filter: object, onEvent: (event: object, relayUrl: string) => void }>,
+ *   pendingPublishes: Array<NostrPublishRequest>,
+ *   inflightPublishes: Array<NostrPublishRequest>,
  * }} SharedRelaySession
  */
 
 /** @type {Map<string, SharedRelaySession>} */
 const sharedRelaySessions = new Map()
 
+/**
+ * 会话是否仍有需要连接的工作（sub 或待发 publish）。
+ * @param {SharedRelaySession} session 会话
+ * @returns {boolean} 是否有活跃工作
+ */
+function hasPendingWork(session) {
+	return session.subs.size  || session.pendingPublishes.length  || session.inflightPublishes.length
+}
+
+/**
+ * 取消会话的空闲回收定时器。
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function clearIdleDrop(session) {
+	if (!session.idleTimer) return
+	clearTimeout(session.idleTimer)
+	session.idleTimer = null
+}
+
+/**
+ * 会话无 sub 时，待 publish 清空后延迟回收空闲 socket（给连续 send 复用窗口）。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @returns {void}
+ */
+function scheduleIdleDrop(relayUrl, session) {
+	if (session.subs.size || session.idleTimer) return
+	session.idleTimer = setTimeout(() => {
+		session.idleTimer = null
+		if (!isLiveSharedSession(relayUrl, session) || hasPendingWork(session)) return
+		sharedRelaySessions.delete(relayUrl)
+		clearSharedRelayReconnect(session)
+		if (session.ws) dropWebSocket(session.ws)
+		session.ws = null
+	}, NOSTR_IDLE_DROP_MS)
+	session.idleTimer.unref?.()
+}
+
 /**
  * @param {string} relayUrl 中继 URL
  * @param {SharedRelaySession} session 会话
@@ -408,7 +466,14 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 	ws.once('close', () => {
 		if (!isLiveSharedSession(relayUrl, session)) return
 		session.ws = null
-		if (!session.subs.size) {
+		// 尚未确认的 inflight publish 重新入队，重连后由 flushPendingPublishes 重发。
+		if (session.inflightPublishes.length) {
+			session.pendingPublishes.push(...session.inflightPublishes)
+			for (const publishRequest of session.inflightPublishes)
+				attachQueuedAbort(session, publishRequest)
+			session.inflightPublishes = []
+		}
+		if (!hasPendingWork(session)) {
 			sharedRelaySessions.delete(relayUrl)
 			return
 		}
@@ -416,6 +481,8 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 	})
 	for (const [subId, sub] of session.subs)
 		try { ws.send(JSON.stringify(['REQ', subId, sub.filter])) } catch { /* ignore */ }
+	flushPendingPublishes(relayUrl, session, ws)
+	if (!hasPendingWork(session)) scheduleIdleDrop(relayUrl, session)
 }
 
 /**
@@ -427,22 +494,19 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
 	if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
 	clearSharedRelayReconnect(session)
-	/**
-	 * @returns {void}
-	 */
+	/** 启动/恢复共享会话连接 */
 	const start = () => {
 		session.reconnectTimer = null
 		if (!isLiveSharedSession(relayUrl, session) || session.connecting || session.ws) return
-		if (!session.subs.size) {
+		if (!hasPendingWork(session)) {
 			sharedRelaySessions.delete(relayUrl)
 			return
 		}
 		session.connecting = true
 		void connectRelay(relayUrl, NOSTR_CONNECT_TIMEOUT_MS).then(ws => {
 			session.connecting = false
-			if (!isLiveSharedSession(relayUrl, session) || !session.subs.size) {
-				if (!session.subs.size && isLiveSharedSession(relayUrl, session))
-					sharedRelaySessions.delete(relayUrl)
+			if (!isLiveSharedSession(relayUrl, session) || !hasPendingWork(session)) {
+				sharedRelaySessions.delete(relayUrl)
 				dropWebSocket(ws)
 				return
 			}
@@ -454,7 +518,7 @@ function scheduleSharedRelayConnect(relayUrl, session, delayMs = 0) {
 				url: relayUrl,
 				err: String(error?.message || error),
 			})
-			if (!session.subs.size) {
+			if (!hasPendingWork(session)) {
 				sharedRelaySessions.delete(relayUrl)
 				return
 			}
@@ -483,7 +547,10 @@ function acquireSharedRelay(relayUrl) {
 		ws: null,
 		connecting: false,
 		reconnectTimer: null,
+		idleTimer: null,
 		subs: new Map(),
+		pendingPublishes: [],
+		inflightPublishes: [],
 	}
 	sharedRelaySessions.set(relayUrl, session)
 	scheduleSharedRelayConnect(relayUrl, session)
@@ -502,9 +569,10 @@ function releaseSharedRelaySub(relayUrl, subscriptionId) {
 	const { ws } = session
 	if (ws?.readyState === WebSocket.OPEN)
 		try { ws.send(JSON.stringify(['CLOSE', subscriptionId])) } catch { /* ignore */ }
-	if (session.subs.size) return
+	if (hasPendingWork(session)) return
 	sharedRelaySessions.delete(relayUrl)
 	clearSharedRelayReconnect(session)
+	clearIdleDrop(session)
 	if (ws) dropWebSocket(ws)
 }
 
@@ -518,11 +586,112 @@ function releaseSharedRelaySub(relayUrl, subscriptionId) {
  */
 function registerSharedRelaySub(session, subscriptionId, filter, onEvent) {
 	session.subs.set(subscriptionId, { filter, onEvent })
+	clearIdleDrop(session)
 	const { ws } = session
 	if (ws?.readyState !== WebSocket.OPEN) return
 	try { ws.send(JSON.stringify(['REQ', subscriptionId, filter])) } catch { /* ignore */ }
 }
 
+/**
+ * 将已入队的 publish 逐个派发到已打开 socket 上；复用 publishEventOnRelay 等 OK 回执。
+ * 每个 publish 独立携带自己的 message/abort 监听，socket 共享安全。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {import('ws').WebSocket} socket 已打开连接
+ * @returns {void}
+ */
+function flushPendingPublishes(relayUrl, session, socket) {
+	const pending = session.pendingPublishes
+	session.pendingPublishes = []
+	for (const publishRequest of pending) {
+		publishRequest.removeAbort?.()
+		publishRequest.onAbort = null
+		publishRequest.removeAbort = null
+		const attempt = ++publishRequest.attempt
+		session.inflightPublishes.push(publishRequest)
+		void publishEventOnRelay(socket, relayUrl, publishRequest.event, publishRequest.signal, () => publishRequest.attempt === attempt)
+			.then(
+				ok => settleInflightPublish(relayUrl, session, publishRequest, attempt, () => publishRequest.resolve(ok)),
+				error => settleInflightPublish(relayUrl, session, publishRequest, attempt, () => publishRequest.reject(error)),
+			)
+	}
+}
+
+/**
+ * 为队列中的 publish 挂上 abort 处理：先移除监听器（释放 signal 对回调/event/session 的引用），
+ * 再从队列删除并 reject。
+ * @param {SharedRelaySession} session 会话
+ * @param {SharedRelaySession['pendingPublishes'][number]} publishRequest 待发请求
+ * @returns {void}
+ */
+function attachQueuedAbort(session, publishRequest) {
+	const { signal, reject } = publishRequest
+	/**
+	 * 处理 abort 事件
+	 */
+	publishRequest.onAbort = () => {
+		publishRequest.removeAbort?.()
+		const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
+		if (pendingIndex < 0) return
+		session.pendingPublishes.splice(pendingIndex, 1)
+		reject(new Error('nostr: aborted'))
+	}
+	/**
+	 * 移除 abort 监听器
+	 */
+	publishRequest.removeAbort = () => {
+		if (signal) signal.removeEventListener('abort', publishRequest.onAbort)
+	}
+	if (signal) signal.addEventListener('abort', publishRequest.onAbort, { once: true })
+}
+
+/**
+ * publish 在 socket 上得到 OK / 失败 / abort 后结算：从 inflight 移除并 settle。
+ * 仅结算仍与当前 attempt 匹配的请求：断线重发后 attempt 已递增，旧尝试的结算在此短路，
+ * 避免提前结算重发后的当前尝试。已被 requeue（断线重发）的请求不在 inflight，跳过结算。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {SharedRelaySession['inflightPublishes'][number]} publishRequest 已发送请求
+ * @param {number} attempt 本次发送的 attempt 标识
+ * @param {() => void} settle 结算回调（resolve/reject）
+ * @returns {void}
+ */
+function settleInflightPublish(relayUrl, session, publishRequest, attempt, settle) {
+	if (publishRequest.attempt !== attempt) return
+	const inflightIndex = session.inflightPublishes.indexOf(publishRequest)
+	if (inflightIndex < 0) return
+	session.inflightPublishes.splice(inflightIndex, 1)
+	settle()
+	if (!hasPendingWork(session)) scheduleIdleDrop(relayUrl, session)
+}
+
+/**
+ * 通过共享 relay 会话发布 EVENT：复用已打开 socket，避免每次 send 重开一条连接（内存泄漏）。
+ * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发。
+ * @param {string} relayUrl 中继 URL
+ * @param {object} event 待发布事件
+ * @param {AbortSignal} [signal] 取消信号
+ * @returns {Promise<boolean>} relay 是否接受 EVENT
+ */
+function publishViaSharedRelay(relayUrl, event, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('nostr: aborted'))
+			return
+		}
+		const session = acquireSharedRelay(relayUrl)
+		clearIdleDrop(session)
+		/** @type {SharedRelaySession['pendingPublishes'][number]} */
+		const publishRequest = { event, signal, attempt: 0, resolve, reject, onAbort: null, removeAbort: null }
+		attachQueuedAbort(session, publishRequest)
+		session.pendingPublishes.push(publishRequest)
+		if (session.ws?.readyState === WebSocket.OPEN)
+			flushPendingPublishes(relayUrl, session, session.ws)
+		else
+			scheduleSharedRelayConnect(relayUrl, session)
+	})
+}
+
 /**
  * 内部：按 rendezvous 键订阅 Nostr kind（topic 不导出）。多订阅共享每 URL 一条连接。
  * @param {string[]} relayUrls 中继 URL 列表

package/files/chunk/store.mjs

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 
 import { isHex64 } from '../../core/hexIds.mjs'
+import { trackFileStream } from '../../node/handles.mjs'
 import { getNodeDir } from '../../node/instance.mjs'
 
 /**
@@ -50,7 +51,7 @@ export async function getChunk(hash) {
  * @returns {import('node:fs').ReadStream} 可读流
  */
 export function createChunkReadStream(hash) {
-	return fs.createReadStream(chunkStorePath(hash))
+	return trackFileStream(fs.createReadStream(chunkStorePath(hash)))
 }
 
 /**
@@ -72,5 +73,5 @@ export async function putChunk(hash, data) {
 export async function putChunkFromStream(hash, readable) {
 	const filePath = chunkStorePath(hash)
 	await fsp.mkdir(dirname(filePath), { recursive: true })
-	await pipeline(readable, fs.createWriteStream(filePath))
+	await pipeline(readable, trackFileStream(fs.createWriteStream(filePath)))
 }

package/index.mjs

@@ -11,6 +11,7 @@ import {
 import { registerLinkProvider } from './link/providers/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
 import {
+	closeNode,
 	getNodeDir,
 	initNode,
 	isNodeInitialized,
@@ -58,6 +59,7 @@ import {
 export {
 	attachReputationSyncWire,
 	attachNodeScopeDefaultFeatures,
+	closeNode,
 	configureLinkRegistry,
 	createGroupLinkSet,
 	createScopedLinkRoom,

package/infra/priority.mjs

@@ -28,9 +28,7 @@ export function getInfraPriority() {
 	return { ...priorityConfig }
 }
 
-/**
- * @returns {void}
- */
+/** 将优先级配置应用到 link registry */
 export function applyPriorityToRegistry() {
 	const registry = getLinkRegistry()
 	if (!priorityConfig.useLocalReputation) {

package/infra/service.mjs

@@ -42,9 +42,7 @@ export function consumeOverlayRateToken(buckets, sender, now, limits) {
 	return true
 }
 
-/**
- * @returns {void}
- */
+/** 安装 overlay 速率门 */
 function installOverlayRateLimit() {
 	const limits = {
 		perMin: Math.max(1, Number(infraTunables.overlayRatePerMin) || 120),
@@ -56,9 +54,7 @@ function installOverlayRateLimit() {
 	})
 }
 
-/**
- * @returns {void}
- */
+/** 移除 overlay 速率门并清空桶 */
 function removeOverlayRateLimit() {
 	clearOverlayRateGate()
 	overlayRateBuckets.clear()

package/link/providers/ble_gatt.mjs

@@ -80,9 +80,7 @@ async function dialBleGatt(options) {
 			cleanup()
 			reject(new Error('p2p: ble_gatt peripheral scan timeout'))
 		}, 8_000)
-		/**
-		 * @returns {void}
-		 */
+		/** 清理扫描超时计时器与监听器并停止 BLE 扫描 */
 		function cleanup() {
 			clearTimeout(deadline)
 			noble.removeListener('discover', onDiscover)
@@ -249,9 +247,7 @@ export function createBleGattLinkProvider() {
 					sessionInbound = handler
 					return () => { sessionInbound = null }
 				},
-				/**
-				 * @returns {void}
-				 */
+				/** 关闭入站 transport */
 				closeTransport() {
 					activeInbound = null
 					sessionInbound = null

package/link/providers/lan_tcp.mjs

@@ -35,9 +35,7 @@ function connectTcp(host, port, timeoutMs = LAN_TCP_CONNECT_TIMEOUT_MS) {
 			conn.off('connect', onConnect)
 			reject(error)
 		}
-		/**
-		 * @returns {void}
-		 */
+		/** TCP 连接成功并返回 socket */
 		function onConnect() {
 			clearTimeout(timer)
 			conn.off('error', onError)
@@ -111,9 +109,7 @@ function attachLengthPrefix(socket, onPayload) {
 			header.writeUInt32BE(body.length)
 			socket.write(Buffer.concat([header, body]))
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 仅移除 data 监听器 */
 		destroy() {
 			socket.off('data', onData)
 		},
@@ -149,9 +145,7 @@ function createTcpPipe(options) {
 		sendFrame(_action, frame) {
 			codec.write(frame)
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 关闭 transport 与 socket */
 		closeTransport() {
 			codec.destroy()
 			socket.destroy()

package/node/handles.mjs

@@ -0,0 +1,49 @@
+/**
+ * 节点生命周期内打开的文件流注册表。
+ *
+ * 文件流（chunk 读流 / 写流）在 Windows 上若未 destroy 会占用文件句柄，
+ * 导致节点目录删除失败。这里集中跟踪，`closeNode()` 通过
+ * `closeAllFileStreams()` 一次性释放全部仍打开的流。
+ */
+
+/** @type {Set<import('node:stream').Readable | import('node:stream').Writable>} */
+const streams = new Set()
+
+/**
+ * 跟踪一个文件流：销毁/关闭/出错时自动从注册表移除。
+ * @template {import('node:stream').Readable | import('node:stream').Writable} T
+ * @param {T} stream 文件流
+ * @returns {T} 原流
+ */
+export function trackFileStream(stream) {
+	streams.add(stream)
+	/** @returns {void} */
+	const forget = () => streams.delete(stream)
+	stream.once('close', forget)
+	stream.once('error', forget)
+	return stream
+}
+
+/**
+ * 关闭并销毁所有仍在打开的文件流（测试 teardown / 节点关闭）。
+ * @returns {Promise<number>} 被销毁的流数量
+ */
+export async function closeAllFileStreams() {
+	const targeted = [...streams]
+	const pending = []
+	for (const stream of targeted) {
+		if (!stream.closed)
+			pending.push(new Promise(resolve => stream.once('close', resolve)))
+		stream.destroy()
+	}
+	await Promise.all(pending)
+	for (const stream of targeted) streams.delete(stream)
+	return targeted.length
+}
+
+/**
+ * @returns {boolean} 是否仍有未释放的文件流（测试断言用）
+ */
+export function hasOpenFileStreams() {
+	return streams.size > 0
+}

package/node/instance.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path'
 
 import { createFsEntityStore } from './entity_store.mjs'
+import { closeAllFileStreams } from './handles.mjs'
 import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './signaling_config.mjs'
 
 /** @typedef {{ warn?: (...args: unknown[]) => void, error?: (...args: unknown[]) => void, info?: (...args: unknown[]) => void, log?: (...args: unknown[]) => void }} NodeLogger */
@@ -37,7 +38,7 @@ export function getRtcPolyfillCacheEpoch() {
  * @returns {NodeRuntime} 初始化后的运行时
  */
 export function initNode(options) {
-	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or resetNodeForTests')
+	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or closeNode')
 	if (options?.logger !== undefined || options?.signaling !== undefined)
 		throw new Error('p2p: initNode only accepts nodeDir/entityStore — use setNodeLogger / setSignalingRuntimeConfig')
 	const nodeDir = path.resolve(options.nodeDir)
@@ -138,11 +139,13 @@ export function onNodeChange(listener) {
 }
 
 /**
- * 测试专用：重置节点运行时。
- * @returns {void}
+ * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时与监听器。
+ * 之后可用 initNode 重新引导。
+ * @returns {Promise<void>}
  */
-export function resetNodeForTests() {
+export async function closeNode() {
 	runtime = null
 	changeListeners.clear()
 	rtcPolyfillCacheEpoch++
+	await closeAllFileStreams()
 }

package/node/reputation_sync.mjs

@@ -78,9 +78,7 @@ function normalizeHashList(list) {
 		.filter(id => isHex64(id)))]
 }
 
-/**
- * @returns {void}
- */
+/** 将当前 sync 配置写盘 */
 function persistSyncConfig() {
 	writeNodeJsonSync(SYNC_DATA_NAME, loadSyncConfig())
 }
@@ -304,9 +302,7 @@ export async function pullReputationFromNode(nodeHash) {
 	return await resultPromise
 }
 
-/**
- * @returns {void}
- */
+/** 重置 sync 运行时（测试用） */
 export function resetReputationSyncForTests() {
 	syncConfig = null
 	detachReputationSyncWire()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.28",
+	"version": "0.0.30",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

package/transport/group_link_set.mjs

@@ -99,9 +99,7 @@ export function createGroupLinkSet(options) {
 		scheduleDial()
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 按成员选择目标并拨号 */
 	function selectAndDial() {
 		if (!autoconnectEnabled || !active) return
 		const targets = dialAll
@@ -119,9 +117,7 @@ export function createGroupLinkSet(options) {
 				void registry.ensureLinkToNode(nodeHash).catch(() => null)
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 延迟调度一次拨号 */
 	function scheduleDial() {
 		if (!autoconnectEnabled || !active || dialTimer) return
 		dialTimer = setTimeout(() => { dialTimer = null; selectAndDial() }, 200)

package/transport/link_registry.mjs

@@ -719,9 +719,7 @@ export function configureLinkRegistry(options = {}) {
 	pendingRegistryOptions = { ...pendingRegistryOptions, ...options }
 }
 
-/**
- * @returns {void}
- */
+/** 重置 link registry 运行时（测试用） */
 export function resetLinkRegistryForTests() {
 	defaultRegistry = null
 	pendingRegistryOptions = null

package/transport/offer_answer.mjs

@@ -48,9 +48,7 @@ export function createBufferedSignalSession(sendRemote) {
 			for (const handler of handlers)
 				handler(message)
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 清空积压消息 */
 		clear() {
 			backlog.length = 0
 			handlers.clear()

package/transport/runtime_bootstrap.mjs

@@ -111,9 +111,7 @@ export function createRuntimeBootstrap(deps) {
 			?? mergeSignalingRelayUrls(getNodeTransportSettings().relayUrls)
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 注册默认 discovery provider（lan/nostr） */
 	function registerDiscoveryDefaults() {
 		const providerIds = new Set(listDiscoveryProviders().map(provider => provider.id))
 		if (!providerIds.has('lan'))
@@ -124,9 +122,7 @@ export function createRuntimeBootstrap(deps) {
 			registerNostrProvider()
 	}
 
-	/**
-	 * @returns {void}
-	 */
+	/** 注册/替换 nostr discovery provider */
 	function registerNostrProvider() {
 		unregisterDiscoveryProvider('nostr')
 		registerDiscoveryProvider(createNostrDiscoveryProvider({

package/utils/async_mutex.mjs

@@ -42,9 +42,7 @@ export async function withAsyncMutex(key, criticalSection) {
 	const lockKey = key
 	const state = mutexState(lockKey)
 	return new Promise((resolve, reject) => {
-		/**
-		 * @returns {void}
-		 */
+		/** 执行临界区并最终释放锁 */
 		const run = () => {
 			Promise.resolve()
 				.then(criticalSection)

package/utils/ttl_map.mjs

@@ -56,9 +56,7 @@ export function createTtlMap(ttlMs, maxSize = 4096) {
 			}
 			return entry.value
 		},
-		/**
-		 * @returns {void}
-		 */
+		/** 清空全部条目 */
 		clear() {
 			map.clear()
 		},