@steve02081504/fount-p2p 0.0.12 → 0.0.13

package/transport/node_scope.mjs

@@ -0,0 +1,289 @@
+import { attachNodeScopeFedChunkResponder } from '../files/chunk_responder.mjs'
+import { attachMailboxWire } from '../mailbox/wire.mjs'
+import { attachPartWire } from '../wire/part_ingress.mjs'
+import { attachPartQueryWire } from '../wire/part_query.mjs'
+
+import { sendToNodeLink, subscribeScope } from './link_registry.mjs'
+
+/** @type {Map<string, Set<(payload: unknown, peerId: string) => void>>} */
+const nodeActionHandlers = new Map()
+
+/** @type {Set<(context: NodeScopeContext, wire: NodeScopeWire) => void>} */
+const nodeScopeWireHooks = new Set()
+
+/** @type {NodeScopeContext} */
+const nodeScopeContext = { replicaUsername: '' }
+
+/** @type {NodeScopeWire | null} */
+let nodeScopeWire = null
+
+/** @type {(() => void) | null} */
+let nodeScopeSubscribeCleanup = null
+
+/** @type {Set<() => void>} */
+const nodeScopeFeatureDisposers = new Set()
+
+/** @type {Map<string, { count: number, disposeCore: () => void }>} */
+const featureAttachRefs = new Map()
+
+/**
+ * @typedef {{ replicaUsername: string }} NodeScopeContext
+ */
+
+/**
+ * @typedef {{
+ *   on: (name: string, handler: (payload: unknown, peerId: string) => void) => () => void
+ *   send: (name: string, payload: unknown, peerId: string | null) => void
+ * }} NodeScopeWire
+ */
+
+/**
+ * @param {string} peerId 对端 nodeHash
+ * @param {string} action 动作名
+ * @param {unknown} payload 载荷
+ * @returns {Promise<boolean>} 是否成功发出
+ */
+const sendNodeAction = (peerId, action, payload) =>
+	sendToNodeLink(peerId, { scope: 'node', action, payload })
+
+/**
+ * @returns {NodeScopeWire} node scope 的 wire 适配器
+ */
+function createNodeScopeWire() {
+	return {
+		/**
+		 * @param {string} name - action 名
+		 * @param {(payload: unknown, peerId: string) => void} handler - 入站处理器
+		 * @returns {() => void} 取消注册的 dispose
+		 */
+		on(name, handler) {
+			if (!nodeActionHandlers.has(name)) nodeActionHandlers.set(name, new Set())
+			nodeActionHandlers.get(name).add(handler)
+			return () => {
+				const set = nodeActionHandlers.get(name)
+				if (!set) return
+				set.delete(handler)
+				if (!set.size) nodeActionHandlers.delete(name)
+			}
+		},
+		/**
+		 * @param {string} name - action 名
+		 * @param {unknown} payload - 出站载荷
+		 * @param {string | null} peerId - 目标 peer，null 时忽略
+		 * @returns {void}
+		 */
+		send(name, payload, peerId) {
+			if (!peerId) return
+			void sendNodeAction(peerId, name, payload).catch(() => { })
+		},
+	}
+}
+
+/**
+ * @returns {boolean} 是否已订阅 node scope
+ */
+export function isNodeScopeSubscribed() {
+	return nodeScopeSubscribeCleanup != null
+}
+
+/**
+ * @param {string} action - action 名
+ * @returns {boolean} 是否已挂载处理器
+ */
+export function hasNodeScopeAction(action) {
+	return (nodeActionHandlers.get(action)?.size ?? 0) > 0
+}
+
+/**
+ * @param {string} action - action 名
+ * @returns {number} 已注册的处理器数量
+ */
+export function countNodeScopeActionHandlers(action) {
+	return nodeActionHandlers.get(action)?.size ?? 0
+}
+
+/**
+ * 测试/调试：直接派发已挂载的 node action。
+ * @param {string} action - action 名
+ * @param {unknown} payload - 载荷
+ * @param {string} peerId - 发送方 nodeHash
+ * @returns {boolean} 是否有处理器被调用
+ */
+export function dispatchNodeScopeAction(action, payload, peerId) {
+	const handlers = nodeActionHandlers.get(action)
+	if (!handlers?.size) return false
+	for (const handler of handlers)
+		try { handler(payload, peerId) } catch { /* ignore */ }
+	return true
+}
+
+/**
+ * @returns {NodeScopeWire | null} 当前 wire，未 ensure 时为 null
+ */
+export function getNodeScopeWire() {
+	return nodeScopeWire
+}
+
+/**
+ * @returns {NodeScopeContext} 可变 node scope 上下文
+ */
+export function getNodeScopeContext() {
+	return nodeScopeContext
+}
+
+/**
+ * 只订阅 node scope 派发，不挂任何 feature。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消订阅的 dispose
+ */
+export function ensureNodeScope(options = {}) {
+	if (options.replicaUsername != null)
+		nodeScopeContext.replicaUsername = String(options.replicaUsername)
+	if (nodeScopeSubscribeCleanup) return nodeScopeSubscribeCleanup
+	nodeScopeSubscribeCleanup = subscribeScope('node', (senderNodeHash, envelope) => {
+		const handlers = nodeActionHandlers.get(envelope.action)
+		if (!handlers?.size) return
+		for (const handler of handlers)
+			try { handler(envelope.payload, senderNodeHash) } catch { /* ignore */ }
+	})
+	if (!nodeScopeWire) {
+		nodeScopeWire = createNodeScopeWire()
+		for (const hook of nodeScopeWireHooks)
+			try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	}
+	return nodeScopeSubscribeCleanup
+}
+
+/**
+ * @param {(context: NodeScopeContext, wire: NodeScopeWire) => void} hook - wire 创建时回调
+ * @returns {() => void} 取消注册的 dispose
+ */
+export function registerNodeScopeWireHook(hook) {
+	nodeScopeWireHooks.add(hook)
+	if (nodeScopeWire)
+		try { hook(nodeScopeContext, nodeScopeWire) } catch { /* ignore */ }
+	return () => nodeScopeWireHooks.delete(hook)
+}
+
+/**
+ * @param {() => void} dispose - feature 卸载函数
+ * @returns {() => void} 包装后的 dispose（同时从跟踪集移除）
+ */
+function trackFeatureDisposer(dispose) {
+	nodeScopeFeatureDisposers.add(dispose)
+	return () => {
+		dispose()
+		nodeScopeFeatureDisposers.delete(dispose)
+	}
+}
+
+/**
+ * 同一 feature 多次 attach 共享一份 wire；dispose 引用计数归零才卸。
+ * @param {string} key - feature 去重键
+ * @param {() => () => void} attachCore - 首次 attach 时执行，返回核心 dispose
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+function attachFeatureRefCounted(key, attachCore) {
+	let entry = featureAttachRefs.get(key)
+	if (!entry) {
+		entry = { count: 0, disposeCore: attachCore() }
+		featureAttachRefs.set(key, entry)
+	}
+	entry.count++
+	return trackFeatureDisposer(() => {
+		const cur = featureAttachRefs.get(key)
+		if (!cur) return
+		cur.count--
+		if (cur.count > 0) return
+		cur.disposeCore()
+		featureAttachRefs.delete(key)
+	})
+}
+
+/**
+ * 自定义 node scope feature（与 mailbox/part 相同 refcount 语义）。
+ * @param {string} key - feature 去重键
+ * @param {(wire: NodeScopeWire, context: NodeScopeContext) => () => void} attachCore - 首次 attach 注册 handler，返回核心 dispose
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 引用计数包装的 dispose
+ */
+export function attachNodeScopeFeature(key, attachCore, options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted(key, () => attachCore(nodeScopeWire, nodeScopeContext))
+}
+
+/**
+ * refcount 挂载 mailbox wire。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeMailbox(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('mailbox', () => attachMailboxWire(nodeScopeContext, nodeScopeWire))
+}
+
+/**
+ * refcount 挂载 part ingress wire。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopePart(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('part', () => attachPartWire(nodeScopeContext, nodeScopeWire))
+}
+
+/**
+ * refcount 挂载 part_query wire。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopePartQuery(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('partQuery', () => attachPartQueryWire(nodeScopeContext, nodeScopeWire))
+}
+
+/**
+ * refcount 挂载 fed chunk responder。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeChunks(options = {}) {
+	ensureNodeScope(options)
+	return attachFeatureRefCounted('chunks', () =>
+		attachNodeScopeFedChunkResponder(() => nodeScopeContext.replicaUsername, nodeScopeWire))
+}
+
+/**
+ * 全业务 preset（等价旧 ensureNodeScopeRuntime 默认行为）。
+ * @param {{ replicaUsername?: string }} [options] - 可选副本用户名
+ * @returns {() => void} 取消全部 preset 挂载的 dispose
+ */
+export function attachUserRoomDefaultWires(options = {}) {
+	const disposers = [
+		attachNodeScopePart(options),
+		attachNodeScopePartQuery(options),
+		attachNodeScopeMailbox(options),
+		attachNodeScopeChunks(options),
+	]
+	return () => {
+		for (const dispose of disposers) dispose()
+	}
+}
+
+/**
+ * 卸掉 feature 挂载；可选保留 node scope 订阅。
+ * @param {{ keepSubscribe?: boolean }} [options] - true 时保留 node scope 订阅
+ * @returns {void}
+ */
+export function stopNodeScopeRuntime(options = {}) {
+	for (const dispose of [...nodeScopeFeatureDisposers]) dispose()
+	nodeScopeFeatureDisposers.clear()
+	for (const entry of featureAttachRefs.values())
+		try { entry.disposeCore() } catch { /* ignore */ }
+	featureAttachRefs.clear()
+	if (options.keepSubscribe) return
+	nodeScopeSubscribeCleanup?.()
+	nodeScopeSubscribeCleanup = null
+	nodeScopeWire = null
+	nodeActionHandlers.clear()
+}

package/transport/offer_answer.mjs

@@ -1,18 +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 上限，防无 handler 时无限堆积 */
+/** 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>} */
@@ -21,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)
@@ -40,8 +36,7 @@ export function createBufferedSignalSession(sendRemote) {
 			return () => handlers.delete(handler)
 		},
 		/**
-		 * 投递信令消息；无 handler 时入 backlog（有界）。
-		 * @param {unknown} message 信令消息
+		 * @param {unknown} message 入站信令消息
 		 * @returns {void}
 		 */
 		deliver(message) {
@@ -54,7 +49,6 @@ export function createBufferedSignalSession(sendRemote) {
 				handler(message)
 		},
 		/**
-		 * 清空 backlog 与 handler。
 		 * @returns {void}
 		 */
 		clear() {
@@ -65,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'
@@ -76,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,
@@ -107,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 {
@@ -136,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))
@@ -148,19 +137,24 @@ 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)
+		const packet = decryptNodeSignalPacket(localIdentity.nodeHash, bytes)
 		if (packet?.type !== 'signal') return
 		const remoteNodeHash = normalizeHex64(packet.from)
 		const connId = String(packet.connId || '')
@@ -170,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 })
@@ -178,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,9 +1,11 @@
 /**
- * 稀疏连接池纯计算逻辑（§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'
@@ -97,9 +99,9 @@ export function selectExploreWithSourceQuota(exploreIds, exploreSources, k, maxP
 	/** @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()) shuffleInPlace(ids)
 	const out = []
@@ -107,12 +109,12 @@ export function selectExploreWithSourceQuota(exploreIds, exploreSources, k, maxP
 	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
@@ -133,7 +135,7 @@ 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)
@@ -292,10 +294,10 @@ export function applyRosterToPeerPool(options) {
 /**
  * 稀疏连接池：优先 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)
@@ -342,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
+}