@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/transport/offer_answer.mjs

@@ -1,15 +1,16 @@
 import { randomBytes } from 'node:crypto'
 
 import { normalizeHex64 } from '../core/hexIds.mjs'
-import { sendSignal } from '../discovery/index.mjs'
+import { decryptNodeSignalPacket, sendNodeSignalPacket } from '../discovery/index.mjs'
 import { listLinkProviders } from '../link/providers/index.mjs'
+import { nodeDebug, shortHash } from '../node/log.mjs'
 
-import { decryptSignalPacket, encryptSignalPacket, nodeRendezvousTopic } from './signal_crypto.mjs'
+/** accept/dial 挂起期间 ICE 信令 backlog 上限 */
+const SIGNAL_BACKLOG_MAX = 64
 
 /**
- * 创建带 backlog 的缓冲信令会话。
  * @param {(message: unknown) => Promise<void>} sendRemote 远端发送回调
- * @returns {{ send: (message: unknown) => Promise<void>, onRemote: (handler: (message: unknown) => void) => () => void, deliver: (message: unknown) => void, clear: () => void }} 信令会话
+ * @returns {object} 信令会话
  */
 export function createBufferedSignalSession(sendRemote) {
 	/** @type {Set<(message: unknown) => void>} */
@@ -18,17 +19,15 @@ export function createBufferedSignalSession(sendRemote) {
 	const backlog = []
 	return {
 		/**
-		 * 发送信令消息到远端。
-		 * @param {unknown} message 信令消息
+		 * @param {unknown} message 待发送信令消息
 		 * @returns {Promise<void>}
 		 */
 		async send(message) {
 			await sendRemote(message)
 		},
 		/**
-		 * 注册远端信令 handler（含 backlog 回放）。
-		 * @param {(message: unknown) => void} handler 入站回调
-		 * @returns {() => void} 取消订阅函数
+		 * @param {(message: unknown) => void} handler 远端消息回调
+		 * @returns {() => void} 取消订阅
 		 */
 		onRemote(handler) {
 			handlers.add(handler)
@@ -37,12 +36,12 @@ export function createBufferedSignalSession(sendRemote) {
 			return () => handlers.delete(handler)
 		},
 		/**
-		 * 投递信令消息；无 handler 时入 backlog。
-		 * @param {unknown} message 信令消息
+		 * @param {unknown} message 入站信令消息
 		 * @returns {void}
 		 */
 		deliver(message) {
 			if (!handlers.size) {
+				if (backlog.length >= SIGNAL_BACKLOG_MAX) backlog.shift()
 				backlog.push(message)
 				return
 			}
@@ -50,7 +49,6 @@ export function createBufferedSignalSession(sendRemote) {
 				handler(message)
 		},
 		/**
-		 * 清空 backlog 与 handler。
 		 * @returns {void}
 		 */
 		clear() {
@@ -61,9 +59,8 @@ export function createBufferedSignalSession(sendRemote) {
 }
 
 /**
- * 判断信令 body 是否为发起方 offer（据此决定入站是否新建应答 PC）。
  * @param {unknown} body 信令 body
- * @returns {boolean} 是 offer 则 true
+ * @returns {boolean} 是否为 WebRTC offer description
  */
 function isOfferSignalBody(body) {
 	return !!body && typeof body === 'object'
@@ -72,30 +69,19 @@ function isOfferSignalBody(body) {
 }
 
 /**
- * 找已注册的 offer/answer provider（按 level 降序的第一个）。
- * @returns {import('../link/providers/index.mjs').LinkProvider | null} 命中的 provider；无则 null
+ * @returns {import('../link/providers/index.mjs').LinkProvider | null} 首个需要 offer/answer 的 provider
  */
 export function findOfferAnswerProvider() {
 	return listLinkProviders().find(provider => provider.caps?.needsOfferAnswer) ?? null
 }
 
 /**
- * Offer/answer glare 拨号控制器（WebRTC 等 needsOfferAnswer provider）。
- * @param {object} deps 依赖注入
- * @param {{ nodeHash: string, nodePubKey: string, secretKey: Uint8Array }} deps.localIdentity 本地身份
- * @param {RTCConfiguration['iceServers']} deps.iceServers ICE 服务器列表
- * @param {string} deps.selfTopic 本机 rendezvous topic
- * @param {Map<string, ReturnType<typeof createBufferedSignalSession>>} deps.signalSessions 按 connId 索引的信令会话
- * @param {(remoteNodeHash: string, link: object) => Promise<void>} deps.registerResolvedLink 注册规范链
- * @param {() => Promise<void>} deps.trimToBudget 超预算驱逐
- * @param {(remoteNodeHash: string) => object | null | undefined} deps.getCanonicalLink 读取当前规范链
- * @returns {{ handleIncomingSignal: (bytes: Uint8Array) => Promise<void>, dialOfferAnswer: (provider: import('../link/providers/index.mjs').LinkProvider, remoteNodeHash: string) => Promise<object | null> }} 入站信令与主动拨号
+ * @param {object} deps 依赖
+ * @returns {object} offer/answer 拨号
  */
 export function createOfferAnswerDial(deps) {
 	const {
 		localIdentity,
-		iceServers,
-		selfTopic,
 		signalSessions,
 		registerResolvedLink,
 		trimToBudget,
@@ -103,28 +89,30 @@ export function createOfferAnswerDial(deps) {
 	} = deps
 
 	/**
-	 * 为单条 PC 创建按 connId 标记的信令会话。
-	 * @param {string} remoteNodeHash 远端节点 64 hex
-	 * @param {string} connId 连接标识
-	 * @returns {ReturnType<typeof createBufferedSignalSession>} 信令会话
+	 * @param {string} remoteNodeHash 远端
+	 * @param {string} connId 连接 id
+	 * @returns {ReturnType<typeof createBufferedSignalSession>} 该连接的缓冲信令会话
 	 */
 	function createConnSession(remoteNodeHash, connId) {
 		const normalized = normalizeHex64(remoteNodeHash)
-		const topic = nodeRendezvousTopic(normalized)
 		return createBufferedSignalSession(async message => {
-			await sendSignal(topic, normalized, encryptSignalPacket(topic, {
+			await sendNodeSignalPacket(normalized, {
 				type: 'signal',
 				from: localIdentity.nodeHash,
 				connId,
 				body: message,
-			}))
+			})
 		})
 	}
 
 	/**
-	 * Offer/answer provider：为一条 connId 会话建链并走 glare 择一。
-	 * @param {{ provider: import('../link/providers/index.mjs').LinkProvider, remoteNodeHash: string, connId: string, session: ReturnType<typeof createBufferedSignalSession>, initiator: boolean }} options 建链参数
-	 * @returns {Promise<object | null>} 当前规范链；失败 null
+	 * @param {object} options 建链参数
+	 * @param {import('../link/providers/index.mjs').LinkProvider} options.provider 链路提供者
+	 * @param {string} options.remoteNodeHash 远端 nodeHash
+	 * @param {string} options.connId 连接 id
+	 * @param {ReturnType<typeof createBufferedSignalSession>} options.session 信令会话
+	 * @param {boolean} options.initiator 是否主动拨号
+	 * @returns {Promise<object | null>} 建链成功返回规范链路，否则 null
 	 */
 	async function buildConnLink({ provider, remoteNodeHash, connId, session, initiator }) {
 		try {
@@ -132,11 +120,16 @@ export function createOfferAnswerDial(deps) {
 			const link = await (initiator ? provider.dial : provider.accept)({
 				nodeHash: remoteNodeHash,
 				signal: session,
-				iceServers,
+				iceServers: deps.iceServers,
 				localIdentity,
 			})
 			if (!link) {
 				signalSessions.delete(connId)
+				nodeDebug('p2p:webrtc null', {
+					peer: shortHash(remoteNodeHash),
+					provider: provider.id,
+					role: initiator ? 'dial' : 'accept',
+				})
 				return null
 			}
 			link.onDown(() => signalSessions.delete(connId))
@@ -144,20 +137,25 @@ export function createOfferAnswerDial(deps) {
 			await registerResolvedLink(remoteNodeHash, link)
 			return getCanonicalLink(remoteNodeHash) ?? null
 		}
-		catch {
+		catch (error) {
 			signalSessions.delete(connId)
+			nodeDebug('p2p:webrtc fail', {
+				peer: shortHash(remoteNodeHash),
+				provider: provider.id,
+				role: initiator ? 'dial' : 'accept',
+				err: String(error?.message || error),
+			})
 			return null
 		}
 	}
 
 	/**
-	 * 处理入站加密信令并可能发起被动建链。
-	 * @param {Uint8Array} bytes 加密信令字节
+	 * @param {Uint8Array} bytes 加密信令
 	 * @returns {Promise<void>}
 	 */
 	async function handleIncomingSignal(bytes) {
-		const packet = decryptSignalPacket(selfTopic, bytes)
-		if (!packet || packet.type !== 'signal') return
+		const packet = decryptNodeSignalPacket(localIdentity.nodeHash, bytes)
+		if (packet?.type !== 'signal') return
 		const remoteNodeHash = normalizeHex64(packet.from)
 		const connId = String(packet.connId || '')
 		if (!remoteNodeHash || remoteNodeHash === localIdentity.nodeHash || !connId) return
@@ -166,6 +164,10 @@ export function createOfferAnswerDial(deps) {
 			if (!isOfferSignalBody(packet.body)) return
 			const provider = findOfferAnswerProvider()
 			if (!provider) return
+			nodeDebug('p2p:webrtc inbound offer', {
+				peer: shortHash(remoteNodeHash),
+				provider: provider.id,
+			})
 			session = createConnSession(remoteNodeHash, connId)
 			signalSessions.set(connId, session)
 			void buildConnLink({ provider, remoteNodeHash, connId, session, initiator: false })
@@ -174,10 +176,9 @@ export function createOfferAnswerDial(deps) {
 	}
 
 	/**
-	 * 经 offer/answer provider 拨号（discovery signal + glare）。
 	 * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
-	 * @param {string} remoteNodeHash 远端 64 hex
-	 * @returns {Promise<object | null>} 当前规范链；失败 null
+	 * @param {string} remoteNodeHash 远端 nodeHash
+	 * @returns {Promise<object | null>} 建链成功返回规范链路，否则 null
 	 */
 	async function dialOfferAnswer(provider, remoteNodeHash) {
 		const connId = randomBytes(16).toString('hex')

package/transport/peer_pool.mjs

@@ -1,13 +1,16 @@
 /**
- * 稀疏连接池纯计算逻辑（§0、§4）：
- * Top-K 信任连接 + M 随机探索，可被 chat shell 与 subfounts 共用。
- * 不含文件 I/O；I/O 层由调用方注入。
+ * 连接池纯计算：
+ * - 群联邦稀疏拨号：trustedSlots + exploreSlots（groupSettings）
+ * - 节点 mesh 保活：N / K_max（routing profile + transport tunables）
+ * 不含文件 I/O；I/O 由调用方注入。
  */
 
+import { compareHex64Asc } from '../core/hexIds.mjs'
 import { loadPeerPoolView, mergeNetworkPeerPools } from '../node/network.mjs'
 import { loadReputation } from '../node/reputation_store.mjs'
 import { isQuarantinedPure } from '../reputation/engine.mjs'
 import { clampReputationScore } from '../reputation/math.mjs'
+import { shuffleInPlace } from '../utils/shuffle.mjs'
 
 /**
  * 解析联邦池槽位参数（从 groupSettings 读取，含低功耗缩减）。
@@ -91,37 +94,27 @@ export function mergeTrustedWithAnchors(existingTrusted, rankedCandidates, limit
  */
 export function selectExploreWithSourceQuota(exploreIds, exploreSources, k, maxPerSource = EXPLORE_MAX_PER_SOURCE) {
 	if (k <= 0 || !exploreIds.length) return []
-	if (!exploreSources?.size) {
-		const copy = [...exploreIds]
-		for (let i = copy.length - 1; i > 0; i--) {
-			const j = Math.floor(Math.random() * (i + 1))
-				;[copy[i], copy[j]] = [copy[j], copy[i]]
-		}
-		return copy.slice(0, k)
-	}
+	if (!exploreSources?.size)
+		return shuffleInPlace([...exploreIds]).slice(0, k)
 	/** @type {Map<string, string[]>} */
 	const bySource = new Map()
 	for (const id of exploreIds) {
-		const src = exploreSources.get(id) || 'unknown'
-		if (!bySource.has(src)) bySource.set(src, [])
-		bySource.get(src).push(id)
+		const source = exploreSources.get(id) || 'unknown'
+		if (!bySource.has(source)) bySource.set(source, [])
+		bySource.get(source).push(id)
 	}
-	for (const ids of bySource.values())
-		for (let i = ids.length - 1; i > 0; i--) {
-			const j = Math.floor(Math.random() * (i + 1))
-				;[ids[i], ids[j]] = [ids[j], ids[i]]
-		}
+	for (const ids of bySource.values()) shuffleInPlace(ids)
 	const out = []
 	/** @type {Map<string, number>} */
 	const picked = new Map()
 	while (out.length < k) {
 		let progressed = false
-		for (const [src, ids] of bySource) {
+		for (const [source, ids] of bySource) {
 			if (out.length >= k) break
-			const idx = picked.get(src) ?? 0
-			if (idx >= maxPerSource || idx >= ids.length) continue
-			out.push(ids[idx])
-			picked.set(src, idx + 1)
+			const index = picked.get(source) ?? 0
+			if (index >= maxPerSource || index >= ids.length) continue
+			out.push(ids[index])
+			picked.set(source, index + 1)
 			progressed = true
 		}
 		if (!progressed) break
@@ -142,13 +135,13 @@ export function selectExploreWithSourceQuota(exploreIds, exploreSources, k, maxP
  *   inRoomNodeHashes?: Set<string> | string[] 群内在线 node_id；有则优先，仅全不可达时用 explore 中非房内节点
  *   hintSources?: Map<string, string> explore 节点来源（用于配额）
  * }} options 选取参数（roster、peers、rep、limits、selfNodeHash）
- * @returns {string[]} 目标 Trystero peerId 列表（去重，长度 ≤ maxPeers）
+ * @returns {string[]} 目标 peerId 列表（去重，长度 ≤ maxPeers）
  */
 export function selectPeerIdsFromPool({ roster, peers, rep, limits, selfNodeHash, inRoomNodeHashes, hintSources }) {
 	const blocked = new Set(peers.blockedPeers)
 	const roomSet = inRoomNodeHashes instanceof Set
 		? inRoomNodeHashes
-		: new Set(Array.isArray(inRoomNodeHashes) ? inRoomNodeHashes : [])
+		: new Set(inRoomNodeHashes || [])
 	const onlineAll = roster.filter(
 		rosterEntry => rosterEntry.peerId
 			&& rosterEntry.remoteNodeHash
@@ -175,10 +168,11 @@ export function selectPeerIdsFromPool({ roster, peers, rep, limits, selfNodeHash
 	}
 
 	const anchoredTrusted = peers.trustedPeers.filter(nodeHash => trustedSet.has(nodeHash))
-	const extraTrusted = [...trustedSet]
-		.filter(nodeHash => !anchoredTrusted.includes(nodeHash))
-		.sort((a, b) => repScore(b, rep) - repScore(a, rep))
-	for (const nodeId of [...anchoredTrusted, ...extraTrusted].slice(0, limits.trustedSlots)) {
+	for (const nodeId of mergeTrustedWithAnchors(
+		anchoredTrusted,
+		[...trustedSet].sort((a, b) => repScore(b, rep) - repScore(a, rep)),
+		limits,
+	)) {
 		if (outPeerIds.size >= limits.maxPeers) break
 		pushNode(nodeId)
 	}
@@ -216,15 +210,14 @@ export function selectPeerIdsFromPool({ roster, peers, rep, limits, selfNodeHash
  * @returns {string[]} 应建链的 nodeHash 列表（去重）
  */
 export function selectLinkTargetsFromMembers({ members, selfNodeHash, rep, peers, limits, anchors = [] }) {
-	const self = String(selfNodeHash || '')
 	const blocked = new Set(peers?.blockedPeers || [])
 	const now = Date.now()
-	const candidates = [...new Set([...members].map(id => String(id)))]
-		.filter(id => id && id !== self && !blocked.has(id) && !isQuarantinedPure(rep, id, now))
+	const candidates = [...new Set(members)]
+		.filter(id => id && id !== selfNodeHash && !blocked.has(id) && !isQuarantinedPure(rep, id, now))
 	const ranked = candidates.slice().sort((a, b) => repScore(b, rep) - repScore(a, rep))
 	const candidateSet = new Set(candidates)
 	// 锚点（如 introducer/creator/seed）必连、且不占 trustedSlots——保证引导期连通。
-	const forced = [...new Set([...anchors].map(id => String(id)))].filter(id => candidateSet.has(id))
+	const forced = [...new Set(anchors)].filter(id => candidateSet.has(id))
 	const chosen = new Set(forced)
 	// trusted 槽只从非锚点候选填：既有 trusted 优先保留，再按信誉补至 trustedSlots。
 	const nonForced = ranked.filter(id => !chosen.has(id))
@@ -237,29 +230,24 @@ export function selectLinkTargetsFromMembers({ members, selfNodeHash, rep, peers
 }
 
 /**
- * 将新 PEX 节点线索合并进 explore 池，并按信誉重新填充 trusted 槽。
- * 纯计算版本，不含 I/O：接受 peers 对象，返回新对象。
- *
+ * 将候选 id 并入 explore，并按信誉重填 trusted。
  * @param {{
  *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[] },
  *   rep: { byNodeHash?: Record<string, { score?: number }> },
- *   hints: string[],
+ *   addIds: Iterable<string>,
  *   limits: ReturnType<typeof resolveFederationPoolLimits>,
- * }} options 合并参数（peers、rep、hints、limits）
- * @returns {{ trustedPeers: string[], explorePeers: string[] }} 更新后的 trusted/explore 列表
+ * }} options 池状态与增量
+ * @returns {{ trustedPeers: string[], explorePeers: string[] }} 重算后的 trusted/explore
  */
-export function applyPexHints({ peers, rep, hints, limits }) {
-	const ids = [...new Set(
-		(Array.isArray(hints) ? hints : [])
-			.map(id => String(id).trim())
-			.filter(Boolean),
-	)]
+function rebuildExploreAndTrusted(options) {
+	const { peers, rep, addIds, limits } = options
+	const blocked = new Set(peers.blockedPeers)
 	const explore = new Set(peers.explorePeers)
-	for (const id of ids)
-		if (!peers.blockedPeers.includes(id)) explore.add(id)
-	const newExplorePeers = [...explore].slice(-500)
+	for (const id of addIds)
+		if (id && !blocked.has(id)) explore.add(id)
+	const newExplorePeers = [...explore].filter(id => !blocked.has(id)).slice(-500)
 	const ranked = [...new Set([...peers.trustedPeers, ...newExplorePeers])]
-		.filter(id => !peers.blockedPeers.includes(id))
+		.filter(id => !blocked.has(id))
 		.sort((a, b) => repScore(b, rep) - repScore(a, rep))
 	return {
 		trustedPeers: mergeTrustedWithAnchors(peers.trustedPeers, ranked, limits, peers.blockedPeers),
@@ -268,57 +256,60 @@ export function applyPexHints({ peers, rep, hints, limits }) {
 }
 
 /**
- * 从 roster 观测中更新 explore 池并重新填充 trusted 槽（纯计算版本）。
- *
+ * PEX 线索并入 explore 并重填 trusted（纯计算）。
  * @param {{
  *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[] },
  *   rep: { byNodeHash?: Record<string, { score?: number }> },
- *   roster: Array<{ remoteNodeHash?: string }>,
+ *   hints: string[],
  *   limits: ReturnType<typeof resolveFederationPoolLimits>,
- * }} options roster 更新参数（peers、rep、roster、limits）
- * @returns {{ trustedPeers: string[], explorePeers: string[] }} 更新后的 trusted/explore 列表
+ * }} options 池状态与 PEX hints
+ * @returns {{ trustedPeers: string[], explorePeers: string[] }} 重算后的 trusted/explore
  */
-export function applyRosterToPeerPool({ peers, rep, roster, limits }) {
-	const explore = new Set(peers.explorePeers)
-	for (const rosterEntry of roster) {
-		const nodeId = rosterEntry.remoteNodeHash?.trim()
-		if (nodeId && !peers.blockedPeers.includes(nodeId)) explore.add(nodeId)
-	}
-	const newExplorePeers = [...explore]
-		.filter(id => !peers.blockedPeers.includes(id))
-		.slice(-500)
-	const candidates = [...new Set([...peers.trustedPeers, ...newExplorePeers])]
-		.filter(id => !peers.blockedPeers.includes(id))
-		.sort((a, b) => repScore(b, rep) - repScore(a, rep))
-	return {
-		trustedPeers: mergeTrustedWithAnchors(peers.trustedPeers, candidates, limits, peers.blockedPeers),
-		explorePeers: newExplorePeers,
-	}
+export function applyPexHints(options) {
+	const { peers, rep, hints, limits } = options
+	return rebuildExploreAndTrusted({
+		peers, rep, limits,
+		addIds: hints || [],
+	})
+}
+
+/**
+ * roster 观测并入 explore 并重填 trusted（纯计算）。
+ * @param {{
+ *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[] },
+ *   rep: { byNodeHash?: Record<string, { score?: number }> },
+ *   roster: { remoteNodeHash?: string }[],
+ *   limits: ReturnType<typeof resolveFederationPoolLimits>,
+ * }} options 池状态与 roster
+ * @returns {{ trustedPeers: string[], explorePeers: string[] }} 重算后的 trusted/explore
+ */
+export function applyRosterToPeerPool(options) {
+	const { peers, rep, roster, limits } = options
+	return rebuildExploreAndTrusted({
+		peers, rep, limits,
+		addIds: roster.map(entry => entry.remoteNodeHash).filter(Boolean),
+	})
 }
 
 /**
  * 稀疏连接池：优先 trusted，再 explore，再其余在线节点。
  * @param {string} groupId 群
- * @param {{ peerId: string, remoteNodeHash?: string }[]} roster Trystero 在线表
+ * @param {{ peerId: string, remoteNodeHash?: string }[]} roster 在线表
  * @param {object} groupSettings 物化群设置
  * @param {string} selfNodeHash 本机 node_id
- * @returns {string[]} 目标 Trystero peerId（去重）
+ * @returns {string[]} 目标 peerId（去重）
  */
 export function pickFederationTargetPeerIds(groupId, roster, groupSettings, selfNodeHash) {
 	const limits = resolveFederationPoolLimits(groupSettings)
 	const peers = loadPeerPoolView(groupId)
 	const rep = loadReputation()
-	const inRoomNodeHashes = roster
-		.map(p => p.remoteNodeHash)
-		.map(id => String(id).trim())
-		.filter(Boolean)
 	return selectPeerIdsFromPool({
 		roster,
 		peers,
 		rep,
 		limits,
 		selfNodeHash,
-		inRoomNodeHashes,
+		inRoomNodeHashes: roster.map(entry => entry.remoteNodeHash).filter(Boolean),
 		hintSources: peers.hintSources,
 	})
 }
@@ -353,3 +344,103 @@ export function reconcilePeerPoolFromRoster(groupId, roster, groupSettings) {
 	const { trustedPeers, explorePeers } = applyRosterToPeerPool({ peers, rep, roster, limits })
 	mergeNetworkPeerPools({ trustedPeers, explorePeers })
 }
+
+/**
+ * Mesh 保活 N/K 槽位（routing profile 可缩 N 与 K_max）。
+ * @param {'default' | 'low'} [routingProfile='default'] 路由 profile
+ * @param {object} [tunables={}] transport tunables
+ * @returns {{ N: number, K_max: number }} mesh 槽位上限 N 与熟人槽 K_max
+ */
+export function resolveMeshPoolLimits(routingProfile = 'default', tunables = {}) {
+	const low = routingProfile === 'low'
+	const N = Math.max(1, Math.min(32, Number(low ? tunables.meshNLow : tunables.meshN) || (low ? 4 : 8)))
+	const K_max = Math.max(0, Math.min(N, Number(low ? tunables.meshKMaxLow : tunables.meshKMax) || (low ? 2 : 5)))
+	return { N, K_max }
+}
+
+/**
+ * 选取 mesh 拨号目标：补齐 K 熟人（可超出当前空位，由调用方先踢探索），再按 N−K 探索配额填空。
+ * @param {{
+ *   selfNodeHash: string,
+ *   trustedPeers: string[],
+ *   exploreCandidates: string[],
+ *   hintSources?: Map<string, string>,
+ *   limits: ReturnType<typeof resolveMeshPoolLimits>,
+ *   connectedHashes: Set<string>,
+ *   rep: { byNodeHash?: Record<string, { score?: number, quarantinedUntil?: number }> },
+ *   blockedPeers?: string[],
+ *   now?: number,
+ * }} options 选取参数
+ * @returns {string[]} 应拨号的 nodeHash（熟人可导致需先驱逐探索）
+ */
+export function selectMeshLinkTargets(options) {
+	const {
+		selfNodeHash,
+		trustedPeers = [],
+		exploreCandidates = [],
+		hintSources,
+		limits,
+		connectedHashes,
+		rep,
+		blockedPeers = [],
+		now = Date.now(),
+	} = options
+	const blocked = new Set(blockedPeers)
+	const connected = connectedHashes
+
+	const eligibleTrusted = [...new Set(trustedPeers)]
+		.filter(id => id && id !== selfNodeHash && !blocked.has(id))
+		.filter(id => !isQuarantinedPure(rep, id, now))
+	const trustedSet = new Set(eligibleTrusted)
+	/** 目标组成：K 熟人槽 + (N−K) 探索槽 */
+	const K = Math.min(limits.K_max, eligibleTrusted.length)
+	let connectedTrusted = 0
+	let connectedExplore = 0
+	for (const id of connected)
+		if (trustedSet.has(id)) connectedTrusted++
+		else connectedExplore++
+	const trustedSlotsLeft = Math.max(0, K - connectedTrusted)
+	const trustedRanked = eligibleTrusted
+		.filter(id => !connected.has(id))
+		.sort((a, b) => repScore(b, rep) - repScore(a, rep))
+	// 熟人缺口优先补齐，即使当前已满 N（调用方应先踢探索腾位）
+	const trustedPick = trustedRanked.slice(0, trustedSlotsLeft)
+
+	const exploreQuota = Math.max(0, limits.N - K)
+	const exploreSlotsLeft = Math.max(0, exploreQuota - connectedExplore)
+	const freeAfterTrustedDial = Math.max(0, limits.N - connected.size - trustedPick.length)
+	const exploreNeed = Math.min(exploreSlotsLeft, freeAfterTrustedDial)
+	const explorePool = [...new Set(exploreCandidates)]
+		.filter(id => id && id !== selfNodeHash && !blocked.has(id) && !connected.has(id) && !trustedSet.has(id))
+		.filter(id => !isQuarantinedPure(rep, id, now))
+	const explorePick = selectExploreWithSourceQuota(explorePool, hintSources, exploreNeed)
+	return [...trustedPick, ...explorePick]
+}
+
+/**
+ * mesh trim：探索链优先驱逐，同档取 scope 权重低、nodeHash 小。
+ * @param {string[]} linkHashes 当前链路 nodeHash
+ * @param {Set<string>} exploreLinkHashes 探索链集合
+ * @param {string[]} trustedPeers 熟人池
+ * @param {(nodeHash: string) => number} scopeWeightFn scope 权重
+ * @returns {string | null} 应驱逐的 nodeHash
+ */
+export function pickMeshEvictionVictim(linkHashes, exploreLinkHashes, trustedPeers, scopeWeightFn) {
+	const trustedSet = new Set(trustedPeers)
+	let victimHash = null
+	let victimScore = Infinity
+	for (const nodeHash of linkHashes) {
+		const isExplore = exploreLinkHashes.has(nodeHash) && !trustedSet.has(nodeHash)
+		const weight = scopeWeightFn(nodeHash)
+		const score = (isExplore ? 0 : 1000) + weight
+		if (
+			victimHash == null
+			|| score < victimScore
+			|| (score === victimScore && compareHex64Asc(nodeHash, victimHash) < 0)
+		) {
+			victimHash = nodeHash
+			victimScore = score
+		}
+	}
+	return victimHash
+}

package/transport/remote_user_room.mjs

@@ -1,5 +1,5 @@
+import { bumpLocalDataRevision } from '../node/local_data_revision.mjs'
 import { registerFederationRoomProvider } from '../registries/room_provider.mjs'
-import { invalidateTrustGraphCache } from '../trust_graph/cache.mjs'
 
 import { closeLink, ensureLinkToNode, getLink } from './link_registry.mjs'
 import { USER_ROOM_SCOPE } from './room_scopes.mjs'
@@ -12,36 +12,33 @@ import { USER_ROOM_SCOPE } from './room_scopes.mjs'
  * }} RemoteUserRoomSlot
  */
 
-/** @type {Map<string, RemoteUserRoomSlot | null>} nodeHash → slot（null 表示加入失败/进行中） */
+/** @type {Map<string, RemoteUserRoomSlot>} nodeHash → slot */
 const slots = new Map()
-/** @type {Map<string, Promise<RemoteUserRoomSlot | null>>} nodeHash → 进行中的 promise */
+/** @type {Map<string, Promise<RemoteUserRoomSlot>>} nodeHash → 进行中的 promise */
 const inflights = new Map()
 
 registerFederationRoomProvider('remote-user-room', () => {
-	return [...slots.values()]
-		.filter(Boolean)
-		.map(s => s.roomSlot)
+	return [...slots.values()].map(s => s.roomSlot)
 })
 
 /**
  * 加入目标节点的用户房间（幂等）。
  * @param {string} username 本地 replica 用户名
  * @param {string} targetNodeHash 目标节点 64 hex
- * @returns {Promise<RemoteUserRoomSlot | null>} 房间槽
+ * @returns {Promise<RemoteUserRoomSlot>} 房间槽
  */
 export async function ensureRemoteUserRoom(username, targetNodeHash) {
 	void username
 	const key = targetNodeHash.toLowerCase()
-	if (slots.has(key)) return slots.get(key) || null
-	const existing = inflights.get(key)
-	if (existing) return await existing
+	const existing = slots.get(key)
+	if (existing) return existing
+	const inflight = inflights.get(key)
+	if (inflight) return await inflight
 
 	const task = (async () => {
 		try {
-			if (!await ensureLinkToNode(key)) {
-				slots.set(key, null)
-				return null
-			}
+			if (!await ensureLinkToNode(key))
+				throw new Error(`p2p: ensureRemoteUserRoom link failed for ${key}`)
 
 			/** @type {import('../registries/room_provider.mjs').FederationRoomSlot} */
 			const roomSlot = {
@@ -66,27 +63,25 @@ export async function ensureRemoteUserRoom(username, targetNodeHash) {
 				 * @returns {void}
 				 */
 				sendToPeer(peerId, actionName, payload) {
-					void getLink(key)?.send({ scope: 'node', action: String(actionName), payload }).catch(() => { })
+					void getLink(key)?.send({ scope: 'node', action: actionName, payload }).catch(() => { })
 				},
 			}
 
 			const slot = {
 				roomSlot,
 				/**
-				 * 关闭远端用户房间链路。
+				 * 关闭远端用户房间链路并释放槽位。
 				 * @returns {Promise<void>} 关闭完成
 				 */
-				leave() { return closeLink(key, 'remote-user-room-release') },
+				leave() {
+					slots.delete(key)
+					return closeLink(key, 'remote-user-room-release')
+				},
 			}
 			slots.set(key, slot)
-			invalidateTrustGraphCache()
+			bumpLocalDataRevision()
 			return slot
 		}
-		catch (error) {
-			console.error('p2p: failed to join remote user room', key, error)
-			slots.set(key, null)
-			return null
-		}
 		finally {
 			inflights.delete(key)
 		}