@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/transport/user_room.mjs

@@ -1,125 +1,55 @@
 import { createHash } from 'node:crypto'
 
-import { attachMailboxWire } from '../mailbox/wire.mjs'
 import { ensureNodeDefaults, getNodeHash } from '../node/identity.mjs'
 import { registerFederationRoomProvider } from '../registries/room_provider.mjs'
-import { attachPartWire } from '../wire/part_ingress.mjs'
-import { attachPartQueryWire } from '../wire/part_query.mjs'
+import { shuffleInPlace } from '../utils/shuffle.mjs'
 
-import { listLinks, sendToNodeLink, subscribeScope, getLinkRegistry } from './link_registry.mjs'
+import { getLinkRegistry, listLinks, sendToNodeLink } from './link_registry.mjs'
+import {
+	attachUserRoomDefaultWires,
+	ensureNodeScope,
+} from './node_scope.mjs'
 import { USER_ROOM_SCOPE } from './room_scopes.mjs'
 
 /**
- * 在 node scope action 表上注册 fed_chunk_get / fed_chunk_data handler，
- * 供用户房间（本地 + 远端）双向 chunk 传输使用。
- * @param {string} username 副本用户名 用户名
- * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire action 表
- * @returns {void}
+ * 经 node scope 向对端发 action。
+ * @param {string} peerId 对端 nodeHash
+ * @param {string} action 动作名
+ * @param {unknown} payload 载荷
+ * @returns {Promise<boolean>} 是否发出
  */
-function attachUserRoomChunkHandlers(username, wire) {
-	import('../files/chunk_responder.mjs').then(({ attachNodeScopeFedChunkResponder }) => {
-		attachNodeScopeFedChunkResponder(username, wire)
-	}).catch(error => console.error('p2p: failed to attach chunk handlers to node scope', error))
-}
+const sendNodeAction = (peerId, action, payload) =>
+	sendToNodeLink(peerId, { scope: 'node', action, payload })
 
-/** @type {Promise<UserRoomSlot | null> | null} */
+/** @type {Promise<UserRoomSlot> | null} */
 let userRoomInflight = null
 
 /** @type {UserRoomSlot | null} */
-export let userRoomSlot = null
-
-/** @type {Map<string, Set<(payload: unknown, peerId: string) => void>>} */
-const nodeActionHandlers = new Map()
-/** @type {Set<(username: string, wire: { on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }) => void>} */
-const nodeScopeWireHooks = new Set()
-/** @type {string} */
-let nodeScopeReplicaUsername = ''
-/** @type {ReturnType<typeof createNodeScopeWire> | null} */
-let nodeScopeWire = null
-let nodeScopeCleanup = null
+let userRoomSlot = null
 
-/**
- * Chat 等非 P2P 模块可向 node scope 注册 fed_emoji 等 handler（避免 p2p→shell 硬依赖）。
- * @param {(username: string, wire: { on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }) => void} hook 注册回调
- * @returns {() => void} 取消注册
- */
-export function registerUserRoomNodeScopeHook(hook) {
-	nodeScopeWireHooks.add(hook)
-	if (nodeScopeWire)
-		try { hook(nodeScopeReplicaUsername, nodeScopeWire) } catch { /* ignore */ }
-	return () => nodeScopeWireHooks.delete(hook)
-}
+/** @type {(() => void) | null} */
+let userRoomDefaultWiresDispose = null
 
 /**
- * 创建 node scope 的 on/send wire 表。
- * @returns {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire 接口
+ * @returns {UserRoomSlot | null} 已创建的用户房间槽，未 ensure 时为 null
  */
-function createNodeScopeWire() {
-	return {
-		/**
-		 * 注册 node scope action handler。
-		 * @param {string} name action 名称
-		 * @param {(payload: unknown, peerId: string) => void} handler 入站回调
-		 * @returns {void}
-		 */
-		on(name, handler) {
-			const key = String(name)
-			if (!nodeActionHandlers.has(key)) nodeActionHandlers.set(key, new Set())
-			nodeActionHandlers.get(key).add(handler)
-		},
-		/**
-		 * 向指定 peer 发送 node scope action。
-		 * @param {string} name action 名称
-		 * @param {unknown} payload 载荷
-		 * @param {string | null} peerId 目标 peer id
-		 * @returns {void}
-		 */
-		send(name, payload, peerId) {
-			if (!peerId) return
-			void sendToNodeLink(peerId, { scope: 'node', action: String(name), payload }).catch(() => { })
-		},
-	}
+export function getUserRoomSlot() {
+	return userRoomSlot
 }
 
 /**
  * 返回当前所有活跃链路的 roster。
- * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 在线 peer 列表
+ * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 活跃链路列表
  */
-function activeLinkRoster() {
+export function activeLinkRoster() {
 	return listLinks().map(({ nodeHash }) => ({ peerId: nodeHash, remoteNodeHash: nodeHash }))
 }
 
 /**
- * 初始化 node scope 订阅与 wire 派发（幂等）。
- * @param {{ replicaUsername?: string }} wireContext 入站上下文
- * @returns {Promise<void>}
- */
-async function ensureNodeScopeRuntime(wireContext) {
-	if (nodeScopeCleanup) return
-	nodeScopeReplicaUsername = String(wireContext.replicaUsername || nodeScopeReplicaUsername || '')
-	nodeScopeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
-		const handlers = nodeActionHandlers.get(String(envelope?.action || ''))
-		if (!handlers?.size) return
-		for (const handler of handlers)
-			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
-	})
-	const wire = createNodeScopeWire()
-	nodeScopeWire = wire
-	attachPartWire({ replicaUsername: wireContext.replicaUsername }, wire)
-	attachPartQueryWire({ replicaUsername: wireContext.replicaUsername }, wire)
-	attachMailboxWire({ replicaUsername: wireContext.replicaUsername }, wire)
-	attachUserRoomChunkHandlers(wireContext.replicaUsername || '', wire)
-	for (const hook of nodeScopeWireHooks)
-		try { hook(wireContext.replicaUsername || '', wire) } catch { /* ignore */ }
-}
-
-/**
- * 用户级 node scope 房间（`fount-node-{nodeHash}`），单节点单实例。
- *
  * @typedef {{
  *   roomId: string
  *   roomSecret: string
- *   room: object
+ *   room: object | null
  *   sendToPeer: (peerId: string, actionName: string, payload: unknown) => void
  *   getRoster: () => Array<{ peerId: string, remoteNodeHash: string | undefined }>
  *   getPeerIdByNodeHash: (nodeHash: string) => string | null
@@ -127,28 +57,31 @@ async function ensureNodeScopeRuntime(wireContext) {
  */
 
 registerFederationRoomProvider('user-room', () => {
-	if (!userRoomSlot) return []
+	const slot = getUserRoomSlot()
+	if (!slot) return []
 	return [{
 		groupId: USER_ROOM_SCOPE,
-		/** @returns {Array<{ peerId: string, remoteNodeHash: string | undefined }>} 房间 roster 列表 */
-		getRoster: () => userRoomSlot.getRoster(),
 		/**
-		 * @param {string} nodeHash 64 位十六进制
-		 * @returns {string | null} 对端 id
+		 * @returns {Array<{ peerId: string, remoteNodeHash: string | undefined }>} 当前 roster
 		 */
-		getPeerIdByNodeHash: nodeHash => userRoomSlot.getPeerIdByNodeHash(nodeHash),
+		getRoster: () => slot.getRoster(),
 		/**
-		 * @param {string} peerId 目标 peer
-		 * @param {string} actionName 节点 scope action
-		 * @param {unknown} payload 载荷
+		 * @param {string} nodeHash - 远端节点 hash
+		 * @returns {string | null} 已连接时返回 peerId，否则 null
+		 */
+		getPeerIdByNodeHash: nodeHash => slot.getPeerIdByNodeHash(nodeHash),
+		/**
+		 * @param {string} peerId - 目标 peer
+		 * @param {string} actionName - node scope action 名
+		 * @param {unknown} payload - 载荷
 		 * @returns {void}
 		 */
-		sendToPeer: (peerId, actionName, payload) => userRoomSlot.sendToPeer(peerId, actionName, payload),
+		sendToPeer: (peerId, actionName, payload) => slot.sendToPeer(peerId, actionName, payload),
 	}]
 })
 
 /**
- * @returns {{ appId: string, password: string, roomId: string, nodeHash: string }} 用户房间参数
+ * @returns {{ appId: string, password: string, roomId: string, nodeHash: string }} user room rendezvous 凭据
  */
 export function resolveUserRoomCredentials() {
 	const nodeHash = getNodeHash()
@@ -162,61 +95,62 @@ export function resolveUserRoomCredentials() {
 }
 
 /**
- * @param {{ replicaUsername?: string }} [wireContext] 入站上下文（part/mailbox 派发用）
- * @returns {Promise<UserRoomSlot | null>} 用户级联邦房间槽
+ * 用户房间槽 + runtime；默认不挂业务 wire（用 `attachUserRoomDefaultWires` / `attachDefaultWires: true`）。
+ * @param {{ replicaUsername?: string, attachDefaultWires?: boolean }} [options] - 副本用户名与是否挂载默认 wire
+ * @returns {Promise<UserRoomSlot>} 用户房间槽
  */
-export async function ensureUserRoom(wireContext = {}) {
-	if (userRoomSlot) return userRoomSlot
+export async function ensureUserRoom(options = {}) {
+	const { attachDefaultWires = false } = options
+	if (options.replicaUsername != null)
+		ensureNodeScope({ replicaUsername: options.replicaUsername })
+	if (userRoomSlot) {
+		if (attachDefaultWires && !userRoomDefaultWiresDispose)
+			userRoomDefaultWiresDispose = attachUserRoomDefaultWires({ replicaUsername: options.replicaUsername })
+		return userRoomSlot
+	}
 	if (userRoomInflight) return await userRoomInflight
 
 	userRoomInflight = (async () => {
 		ensureNodeDefaults()
-		try {
-			await getLinkRegistry().ensureRuntime()
-			await ensureNodeScopeRuntime(wireContext)
-			const creds = resolveUserRoomCredentials()
-			/** @type {UserRoomSlot} */
-			userRoomSlot = {
-				roomId: creds.roomId,
-				roomSecret: creds.password,
-				room: null,
-				/**
-				 * 经 node scope 向 peer 发送 action。
-				 * @param {string} peerId 目标 peer id
-				 * @param {string} actionName action 名称
-				 * @param {unknown} payload 载荷
-				 * @returns {void}
-				 */
-				sendToPeer(peerId, actionName, payload) {
-					void sendToNodeLink(peerId, { scope: 'node', action: String(actionName), payload }).catch(() => { })
-				},
-				/**
-				 * 返回当前活跃链路 roster。
-				 * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 在线 peer 列表
-				 */
-				getRoster: () => activeLinkRoster(),
-				/**
-				 * 按 nodeHash 查找 peer id。
-				 * @param {string} nodeHash 目标节点 64 hex
-				 * @returns {string | null} 对端 id；无链路时为 null
-				 */
-				getPeerIdByNodeHash(nodeHash) {
-					return getLinkRegistry().getLink(nodeHash) ? String(nodeHash) : null
-				},
-			}
-			return userRoomSlot
-		}
-		catch (error) {
-			console.error('p2p: node scope init failed', error)
-			userRoomSlot = null
-			return null
-		}
-		finally {
-			userRoomInflight = null
+		await getLinkRegistry().ensureRuntime()
+		ensureNodeScope({ replicaUsername: options.replicaUsername })
+		if (attachDefaultWires && !userRoomDefaultWiresDispose)
+			userRoomDefaultWiresDispose = attachUserRoomDefaultWires({ replicaUsername: options.replicaUsername })
+		const creds = resolveUserRoomCredentials()
+		userRoomSlot = {
+			roomId: creds.roomId,
+			roomSecret: creds.password,
+			room: null,
+			/**
+			 * @param {string} peerId - 目标 peer
+			 * @param {string} actionName - node scope action 名
+			 * @param {unknown} payload - 载荷
+			 * @returns {void}
+			 */
+			sendToPeer(peerId, actionName, payload) {
+				void sendNodeAction(peerId, actionName, payload).catch(() => { })
+			},
+			/**
+			 * @returns {Array<{ peerId: string, remoteNodeHash: string }>} 当前活跃链路 roster
+			 */
+			getRoster: () => activeLinkRoster(),
+			/**
+			 * @param {string} nodeHash - 远端节点 hash
+			 * @returns {string | null} 已连接时返回 peerId，否则 null
+			 */
+			getPeerIdByNodeHash(nodeHash) {
+				return getLinkRegistry().getLink(nodeHash) ? nodeHash : null
+			},
 		}
+		return userRoomSlot
 	})()
 
-	return await userRoomInflight
+	try {
+		return await userRoomInflight
+	}
+	finally {
+		userRoomInflight = null
+	}
 }
 
 /**
@@ -225,24 +159,19 @@ export async function ensureUserRoom(wireContext = {}) {
  * @param {unknown} payload 载荷
  * @param {string | null} [exceptPeerId] 跳过的 peer
  * @param {number} [limit] 最多转发 peer 数
- * @returns {Promise<number>} 实际转发的 peer 数
+ * @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 slot = await ensureUserRoom({ replicaUsername: username })
-	if (!slot) return 0
 	const body = { ...payload, nodeHash: getNodeHash() }
 	let sent = 0
-	const peers = [...slot.getRoster()
-		.filter(({ peerId }) => peerId && peerId !== exceptPeerId)]
-	for (let swapIndex = peers.length - 1; swapIndex > 0; swapIndex--) {
-		const pickIndex = Math.floor(Math.random() * (swapIndex + 1))
-		;[peers[swapIndex], peers[pickIndex]] = [peers[pickIndex], peers[swapIndex]]
-	}
+	const peers = shuffleInPlace(activeLinkRoster()
+		.filter(({ peerId }) => peerId && peerId !== exceptPeerId))
 	for (const { peerId } of peers)
 		try {
-			if (await sendToNodeLink(peerId, { scope: 'node', action: String(actionName), payload: body }))
+			if (await sendNodeAction(peerId, actionName, body))
 				sent++
 			if (sent >= fanoutLimit) break
 		}
@@ -250,3 +179,6 @@ export async function deliverToUserRoomPeers(username, actionName, payload, exce
 
 	return sent
 }
+
+/** 再导出：node-scope 订阅与默认 wires（见 `node_scope.mjs`）。 */
+export { attachUserRoomDefaultWires, ensureNodeScope } from './node_scope.mjs'

package/trust_graph/build.mjs

@@ -3,7 +3,6 @@ import { loadNetwork } from '../node/network.mjs'
 import { loadReputation } from '../node/reputation_store.mjs'
 import { listFederationRoomSlots } from '../registries/room_provider.mjs'
 import { isQuarantinedPure } from '../reputation/engine.mjs'
-import { ensureUserRoom } from '../transport/user_room.mjs'
 
 import { getCachedTrustGraph } from './cache.mjs'
 import { mergeGraph, pickTopFromGraph } from './engine.mjs'
@@ -90,7 +89,6 @@ export async function buildMergedGraph(username) {
  * @returns {Promise<TrustNode[]>} 按信誉降序
  */
 export async function pickTopNodes(username, limit = trustGraphTunables.pickTopNodesDefaultLimit) {
-	await ensureUserRoom({ replicaUsername: username })
 	const rep = loadReputation()
 	const quarantined = new Set(
 		Object.keys(rep.byNodeHash || {}).filter(id => isQuarantinedPure(rep, id)),

package/trust_graph/cache.mjs

@@ -1,10 +1,13 @@
-/** @type {Map<string, { graph: Map<string, object>, builtAt: number, revision: number }>} */
+import { getLocalDataRevision } from '../node/local_data_revision.mjs'
+
+/** @type {Map<string, { graph: Map<string, object>, builtAt: number, revision: number, dataRevision: number }>} */
 const cacheByUsername = new Map()
 let revision = 0
 
 const DEFAULT_TTL_MS = 30_000
 
 /**
+ * 显式失效（测试 / 特殊路径）；常态依赖 local_data_revision。
  * @returns {void}
  */
 export function invalidateTrustGraphCache() {
@@ -21,11 +24,17 @@ export function invalidateTrustGraphCache() {
 export async function getCachedTrustGraph(username, build, ttlMs = DEFAULT_TTL_MS) {
 	const key = String(username || '')
 	const now = Date.now()
+	const dataRevision = getLocalDataRevision()
 	const cached = cacheByUsername.get(key)
-	if (cached && cached.revision === revision && now - cached.builtAt < ttlMs)
+	if (
+		cached
+		&& cached.revision === revision
+		&& cached.dataRevision === dataRevision
+		&& now - cached.builtAt < ttlMs
+	)
 		return cached.graph
 
 	const graph = await build()
-	cacheByUsername.set(key, { graph, builtAt: now, revision })
+	cacheByUsername.set(key, { graph, builtAt: now, revision, dataRevision })
 	return graph
 }

package/trust_graph/registry.mjs

@@ -9,11 +9,11 @@ export const DEFAULT_TRUST_GRAPH_OWNER = 'default'
 
 /**
  * @param {string} ownerId 注册方（如 chat）
- * @param {import('./registry.mjs').TrustGraphProvider} impl 信任图实现
+ * @param {import('./registry.mjs').TrustGraphProvider} implementation 信任图实现
  * @returns {void}
  */
-export function registerTrustGraphProvider(ownerId, impl) {
-	providersByOwner.set(String(ownerId), impl)
+export function registerTrustGraphProvider(ownerId, implementation) {
+	providersByOwner.set(String(ownerId), implementation)
 }
 
 /** @returns {void} */
@@ -26,10 +26,10 @@ export function clearTrustGraphProvider() {
  * @returns {import('./registry.mjs').TrustGraphProvider} 已注册实现
  */
 export function requireTrustGraphProvider(ownerId = DEFAULT_TRUST_GRAPH_OWNER) {
-	const impl = providersByOwner.get(String(ownerId))
-	if (!impl)
+	const implementation = providersByOwner.get(String(ownerId))
+	if (!implementation)
 		throw new Error(`p2p: registerTrustGraphProvider('${ownerId}') must run before trust graph fanout`)
-	return impl
+	return implementation
 }
 
 /** @returns {import('./registry.mjs').TrustGraphProvider} 默认信任图实现 */

package/trust_graph/send.mjs

@@ -5,7 +5,6 @@ import { listFederationRoomSlots } from '../registries/room_provider.mjs'
 import { isQuarantinedPure } from '../reputation/engine.mjs'
 import { sendToNodeLink } from '../transport/link_registry.mjs'
 import { USER_ROOM_SCOPE } from '../transport/room_scopes.mjs'
-import { ensureUserRoom } from '../transport/user_room.mjs'
 
 import { buildMergedGraph } from './build.mjs'
 import { pickTopFromGraph } from './engine.mjs'
@@ -23,10 +22,9 @@ import trustGraphTunables from './tunables.json' with { type: 'json' }
 export async function sendToNode(username, targetNodeHash, actionName, payload, graph) {
 	const target = normalizeHex64(targetNodeHash) || String(targetNodeHash || '').trim().toLowerCase()
 	if (!isHex64(target)) return false
-	await ensureUserRoom({ replicaUsername: username })
 
 	// 已直连 peer 不经 trust-graph scope 也应能收发 node scope action（非成员 CAS chunk / follow hint 等）
-	if (await sendToNodeLink(target, { scope: 'node', action: String(actionName), payload }))
+	if (await sendToNodeLink(target, { scope: 'node', action: actionName, payload }))
 		return true
 
 	const merged = graph ?? await buildMergedGraph(username)
@@ -73,7 +71,6 @@ export async function sendToNode(username, targetNodeHash, actionName, payload,
  * @returns {Promise<number>} 发送次数
  */
 export async function fanoutToTopNodes(username, actionName, payload, limit) {
-	await ensureUserRoom({ replicaUsername: username })
 	const graph = await buildMergedGraph(username)
 	const k = limit ?? resolveFederationFanoutTopK(graph.size, trustGraphTunables)
 	const rep = loadReputation()

package/utils/async_mutex.mjs

@@ -34,11 +34,11 @@ function releaseMutex(lockKey, state) {
 
 /**
  * @param {string} key 锁键
- * @param {() => Promise<T>} fn 临界区
- * @returns {Promise<T>} `fn` 的解析结果
+ * @param {() => Promise<T>} criticalSection 临界区
+ * @returns {Promise<T>} `criticalSection` 的解析结果
  * @template T
  */
-export async function withAsyncMutex(key, fn) {
+export async function withAsyncMutex(key, criticalSection) {
 	const lockKey = String(key)
 	const state = mutexState(lockKey)
 	return new Promise((resolve, reject) => {
@@ -47,7 +47,7 @@ export async function withAsyncMutex(key, fn) {
 		 */
 		const run = () => {
 			Promise.resolve()
-				.then(fn)
+				.then(criticalSection)
 				.then(resolve, reject)
 				.finally(() => releaseMutex(lockKey, state))
 		}

package/utils/emit_safe.mjs

@@ -0,0 +1,11 @@
+/**
+ * 调用一组 listener，单次抛错不影响其余。
+ * @param {Iterable<Function>} listeners 回调集合
+ * @param {...unknown} listenerArguments 传给每个 listener 的参数
+ * @returns {void}
+ */
+export function emitSafe(listeners, ...listenerArguments) {
+	for (const listener of listeners)
+		try { listener(...listenerArguments) }
+		catch { /* ignore */ }
+}

package/utils/json_io.mjs

@@ -11,9 +11,9 @@ export async function readJsonFile(filePath) {
 		const raw = await fsp.readFile(filePath, 'utf8')
 		return JSON.parse(raw)
 	}
-	catch (err) {
-		if (/** @type {NodeJS.ErrnoException} */ err.code === 'ENOENT') return null
-		throw err
+	catch (error) {
+		if (/** @type {NodeJS.ErrnoException} */ error.code === 'ENOENT') return null
+		throw error
 	}
 }
 
@@ -24,9 +24,9 @@ export async function readJsonFile(filePath) {
  */
 export async function writeJsonFile(filePath, data) {
 	await fsp.mkdir(path.dirname(filePath), { recursive: true })
-	const tmp = `${filePath}.tmp`
-	await fsp.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
-	await fsp.rename(tmp, filePath)
+	const temporaryPath = `${filePath}.tmp`
+	await fsp.writeFile(temporaryPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+	await fsp.rename(temporaryPath, filePath)
 }
 
 /**
@@ -38,9 +38,9 @@ export function readJsonFileSync(filePath) {
 		const raw = fs.readFileSync(filePath, 'utf8')
 		return JSON.parse(raw)
 	}
-	catch (err) {
-		if (/** @type {NodeJS.ErrnoException} */ err.code === 'ENOENT') return null
-		throw err
+	catch (error) {
+		if (/** @type {NodeJS.ErrnoException} */ error.code === 'ENOENT') return null
+		throw error
 	}
 }
 
@@ -51,7 +51,7 @@ export function readJsonFileSync(filePath) {
  */
 export function writeJsonFileSync(filePath, data) {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true })
-	const tmp = `${filePath}.tmp`
-	fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
-	fs.renameSync(tmp, filePath)
+	const temporaryPath = `${filePath}.tmp`
+	fs.writeFileSync(temporaryPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+	fs.renameSync(temporaryPath, filePath)
 }

package/utils/map_pool.mjs

@@ -2,11 +2,11 @@
  * 有限并发 map（进程内，无外部依赖）。
  * @template T, R
  * @param {T[]} items 待处理项
- * @param {(item: T, index: number) => Promise<R>} fn 异步映射
+ * @param {(item: T, index: number) => Promise<R>} mapper 异步映射
  * @param {number} concurrency 并发上限
  * @returns {Promise<R[]>} 与 items 同序的结果
  */
-export async function mapPool(items, fn, concurrency) {
+export async function mapPool(items, mapper, concurrency) {
 	if (!items.length) return []
 	const limit = Math.max(1, Math.min(concurrency, items.length))
 	/** @type {R[]} */
@@ -16,9 +16,9 @@ export async function mapPool(items, fn, concurrency) {
 	/** @returns {Promise<void>} */
 	const worker = async () => {
 		for (; ;) {
-			const i = nextIndex++
-			if (i >= items.length) return
-			results[i] = await fn(items[i], i)
+			const index = nextIndex++
+			if (index >= items.length) return
+			results[index] = await mapper(items[index], index)
 		}
 	}
 

package/utils/shuffle.mjs

@@ -0,0 +1,13 @@
+/**
+ * Fisher–Yates 原地洗牌。
+ * @template T
+ * @param {T[]} arr 待洗牌数组（原地修改）
+ * @returns {T[]} 同一数组引用
+ */
+export function shuffleInPlace(arr) {
+	for (let i = arr.length - 1; i > 0; i--) {
+		const j = Math.floor(Math.random() * (i + 1))
+		;[arr[i], arr[j]] = [arr[j], arr[i]]
+	}
+	return arr
+}

package/utils/ttl_map.mjs

@@ -1,21 +1,46 @@
 /**
- * 带 TTL 的 Map：get 时惰性过期删除。
+ * 带 TTL 的 Map：get 时惰性过期；set 时在超上限下先清过期再 LRU 驱逐。
  * @template T
  * @param {number} ttlMs 存活毫秒
- * @returns {{ ttlMs: number, set: (key: string, value: T) => void, get: (key: string, now?: number) => T | null, clear: () => void }} TTL Map 句柄
+ * @param {number} [maxSize=4096] 最大条目（防只写不读时过期项堆积）
+ * @returns {{ ttlMs: number, maxSize: number, size: () => number, set: (key: string, value: T) => void, get: (key: string, now?: number) => T | null, clear: () => void }} TTL Map 句柄
  */
-export function createTtlMap(ttlMs) {
+export function createTtlMap(ttlMs, maxSize = 4096) {
+	const cap = Math.max(1, Math.floor(Number(maxSize) || 4096))
 	/** @type {Map<string, { value: T, seenAt: number }>} */
 	const map = new Map()
+
+	/**
+	 * 删除过期项；若仍满则按插入序驱逐最旧。
+	 * @param {number} now 当前时间
+	 * @returns {void}
+	 */
+	function prune(now) {
+		for (const [key, entry] of map)
+			if (now - entry.seenAt > ttlMs) map.delete(key)
+		while (map.size >= cap) {
+			const oldest = map.keys().next().value
+			map.delete(oldest)
+		}
+	}
+
 	return {
 		ttlMs,
+		maxSize: cap,
+		/**
+		 * @returns {number} 当前条目数（含未 get 的过期项）
+		 */
+		size: () => map.size,
 		/**
 		 * @param {string} key 键
 		 * @param {T} value 值
 		 * @returns {void}
 		 */
 		set(key, value) {
-			map.set(key, { value, seenAt: Date.now() })
+			const now = Date.now()
+			if (map.has(key)) map.delete(key)
+			if (map.size >= cap) prune(now)
+			map.set(key, { value, seenAt: now })
 		},
 		/**
 		 * @param {string} key 键

package/wire/ingress.mjs

@@ -19,7 +19,7 @@ export function isPlainObject(value) {
  * @returns {Record<string, unknown> | null} 解析失败或非对象时为 null
  */
 export function parseInboundJson(raw) {
-	if (raw == null) return null
+	if (!raw) return null
 	const text = typeof raw === 'string'
 		? raw
 		: Buffer.isBuffer(raw)