@steve02081504/fount-p2p 0.0.0

package/transport/peer_identity_maps.mjs

@@ -0,0 +1,94 @@
+/**
+ * 按在线 peer 集合将 roster 分为 live 与 stale。
+ * @param {Array<{ peerId: string, remoteNodeHash?: string }>} rosterEntries roster 条目
+ * @param {Iterable<string>} livePeerIds 当前在线 peer id 集合
+ * @returns {{ live: Array<{ peerId: string, remoteNodeHash?: string }>, stale: Array<{ peerId: string, remoteNodeHash?: string }> }} 分组结果
+ */
+export function partitionRosterByLiveness(rosterEntries, livePeerIds) {
+	const liveSet = livePeerIds instanceof Set ? livePeerIds : new Set(livePeerIds)
+	/** @type {Array<{ peerId: string, remoteNodeHash?: string }>} */
+	const live = []
+	/** @type {Array<{ peerId: string, remoteNodeHash?: string }>} */
+	const stale = []
+	for (const entry of rosterEntries) {
+		if (!entry?.peerId) continue
+		const bucket = liveSet.has(entry.peerId) ? live : stale
+		bucket.push(entry)
+	}
+	return { live, stale }
+}
+
+/**
+ * 从 peer↔node 映射中移除离线条目。
+ * @param {Map<string, string>} peerToNode 对端 id → nodeHash
+ * @param {Map<string, string>} nodeToPeer nodeHash → 对端 id
+ * @param {Iterable<string>} livePeerIds 当前在线 peer id 集合
+ * @returns {Array<{ peerId: string, remoteNodeHash?: string }>} 被移除的 stale 条目
+ */
+export function pruneStaleRosterEntries(peerToNode, nodeToPeer, livePeerIds) {
+	const entries = [...peerToNode.entries()].map(([peerId, remoteNodeHash]) => ({ peerId, remoteNodeHash }))
+	const { stale } = partitionRosterByLiveness(entries, livePeerIds)
+	for (const { peerId, remoteNodeHash } of stale) {
+		peerToNode.delete(peerId)
+		if (remoteNodeHash && nodeToPeer.get(remoteNodeHash) === peerId) nodeToPeer.delete(remoteNodeHash)
+	}
+	return stale
+}
+
+/**
+ * 创建 peer id 与 nodeHash 双向映射及 roster 查询辅助。
+ * @param {object} [opts] 选项
+ * @param {() => Iterable<string>} [opts.getLivePeerIds] 获取当前在线 peer id 的回调
+ * @param {(stale: Array<{ peerId: string, remoteNodeHash?: string }>) => void} [opts.onStalePruned] stale 条目被清理时的回调
+ * @returns {{ peerToNode: Map<string, string>, nodeToPeer: Map<string, string>, getRoster: () => Array<{ peerId: string, remoteNodeHash: string | undefined }>, getPeerIdByNodeHash: (nodeHash: string) => string | null, onPeerLeave: (peerId: string) => void }} 映射与查询接口
+ */
+export function createPeerIdentityMaps(opts = {}) {
+	/** @type {Map<string, string>} */
+	const peerToNode = new Map()
+	/** @type {Map<string, string>} */
+	const nodeToPeer = new Map()
+	const getLivePeerIds = typeof opts.getLivePeerIds === 'function' ? opts.getLivePeerIds : null
+	const onStalePruned = typeof opts.onStalePruned === 'function' ? opts.onStalePruned : null
+
+	/**
+	 * 根据 live peer 集合清理 stale 映射。
+	 * @returns {void}
+	 */
+	const reconcile = () => {
+		if (!getLivePeerIds) return
+		const stale = pruneStaleRosterEntries(peerToNode, nodeToPeer, getLivePeerIds())
+		if (stale.length && onStalePruned) onStalePruned(stale)
+	}
+
+	return {
+		peerToNode,
+		nodeToPeer,
+		/**
+		 * 返回当前 roster（会先 reconcile stale 条目）。
+		 * @returns {Array<{ peerId: string, remoteNodeHash: string | undefined }>} roster 列表
+		 */
+		getRoster() {
+			reconcile()
+			return [...peerToNode.entries()].map(([peerId, remoteNodeHash]) => ({ peerId, remoteNodeHash }))
+		},
+		/**
+		 * 按 nodeHash 查找对应 peer id。
+		 * @param {string} targetNodeHash 目标节点 64 hex
+		 * @returns {string | null} 对端 id；无映射时为 null
+		 */
+		getPeerIdByNodeHash(targetNodeHash) {
+			reconcile()
+			return nodeToPeer.get(String(targetNodeHash).trim().toLowerCase()) || null
+		},
+		/**
+		 * peer 离线时从映射中移除。
+		 * @param {string} peerId 离线的 peer id
+		 * @returns {void}
+		 */
+		onPeerLeave(peerId) {
+			const remote = peerToNode.get(peerId)
+			if (remote) nodeToPeer.delete(remote)
+			peerToNode.delete(peerId)
+		},
+	}
+}

package/transport/peer_pool.mjs

@@ -0,0 +1,355 @@
+/**
+ * 稀疏连接池纯计算逻辑（§0、§4）：
+ * Top-K 信任连接 + M 随机探索，可被 chat shell 与 subfounts 共用。
+ * 不含文件 I/O；I/O 层由调用方注入。
+ */
+
+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'
+
+/**
+ * 解析联邦池槽位参数（从 groupSettings 读取，含低功耗缩减）。
+ * @param {object | undefined} groupSettings 群设置
+ * @returns {{
+ *   trustedSlots: number,
+ *   exploreSlots: number,
+ *   maxPeers: number,
+ *   gossipTtl: number,
+ *   wantIdsBudget: number,
+ *   batterySaver: boolean,
+ * }} 解析后的联邦池参数
+ */
+export function resolveFederationPoolLimits(groupSettings = {}) {
+	const battery = !!groupSettings.batterySaver
+	const trustedSlots = battery
+		? 2
+		: Math.max(1, Math.min(32, Number(groupSettings.trustedPeerSlots) || 8))
+	const exploreSlots = battery
+		? 1
+		: Math.max(0, Math.min(16, Number(groupSettings.explorePeerSlots) || 4))
+	const maxPeersRaw = Number(groupSettings.maxPeers)
+	const maxPeers = Number.isFinite(maxPeersRaw) && maxPeersRaw > 0
+		? Math.min(64, Math.floor(maxPeersRaw))
+		: Math.min(64, Math.max(trustedSlots + exploreSlots, 24))
+	let trustedOut = trustedSlots
+	let exploreOut = exploreSlots
+	if (trustedOut + exploreOut > maxPeers) {
+		trustedOut = Math.min(trustedOut, maxPeers)
+		exploreOut = Math.min(exploreOut, Math.max(0, maxPeers - trustedOut))
+	}
+	const gossipTtl = Math.max(0, Math.min(8, Number.isFinite(Number(groupSettings.gossipTtl)) ? Number(groupSettings.gossipTtl) : 2))
+	const wantIdsBudget = Math.max(4, Math.min(128, Number(groupSettings.wantIdsBudget) || 16))
+	return {
+		trustedSlots: trustedOut,
+		exploreSlots: exploreOut,
+		maxPeers,
+		gossipTtl,
+		wantIdsBudget,
+		batterySaver: battery,
+	}
+}
+
+/**
+ * @param {string} nodeId 节点 id
+ * @param {{ byNodeHash?: Record<string, { score?: number }> }} rep 信誉表
+ * @returns {number} 排序分
+ */
+function repScore(nodeId, rep) {
+	const score = Number(rep.byNodeHash?.[nodeId]?.score ?? 0)
+	return clampReputationScore(Number.isFinite(score) ? score : 0)
+}
+
+/** explore 选取时单 source 上限 */
+export const EXPLORE_MAX_PER_SOURCE = 3
+
+/**
+ * trusted 锚点优先保留，再按信誉填充剩余槽位。
+ * @param {string[]} existingTrusted 既有 trusted
+ * @param {string[]} rankedCandidates 信誉排序候选
+ * @param {ReturnType<typeof resolveFederationPoolLimits>} limits 槽位
+ * @param {string[]} [blockedPeers] 拉黑列表
+ * @returns {string[]} 新 trusted 列表
+ */
+export function mergeTrustedWithAnchors(existingTrusted, rankedCandidates, limits, blockedPeers = []) {
+	const blocked = new Set(blockedPeers)
+	const candidateSet = new Set(rankedCandidates.filter(id => id && !blocked.has(id)))
+	const anchored = existingTrusted.filter(id => id && !blocked.has(id) && candidateSet.has(id))
+	const anchoredSet = new Set(anchored)
+	const fill = rankedCandidates.filter(id => id && !blocked.has(id) && !anchoredSet.has(id))
+	return [...anchored, ...fill].slice(0, limits.trustedSlots)
+}
+
+/**
+ * 按 source 轮询选取 explore，限制单源占比。
+ * @param {string[]} exploreIds 候选 nodeHash
+ * @param {Map<string, string> | undefined} exploreSources nodeHash → source
+ * @param {number} k 选取数量
+ * @param {number} [maxPerSource=EXPLORE_MAX_PER_SOURCE] 每源上限
+ * @returns {string[]} 选取结果
+ */
+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)
+	}
+	/** @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)
+	}
+	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]]
+		}
+	const out = []
+	/** @type {Map<string, number>} */
+	const picked = new Map()
+	while (out.length < k) {
+		let progressed = false
+		for (const [src, 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)
+			progressed = true
+		}
+		if (!progressed) break
+	}
+	return out
+}
+
+/**
+ * 稀疏连接池纯选取：给定在线列表、已持久化 peers 状态与信誉表，
+ * 输出按 Top-K trusted + M random explore + 剩余按信誉补至 maxPeers 的 peerId 列表。
+ *
+ * @param {{
+ *   roster: Array<{ peerId: string, remoteNodeHash?: string }>,
+ *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[] },
+ *   rep: { byNodeHash?: Record<string, { score?: number }> },
+ *   limits: ReturnType<typeof resolveFederationPoolLimits>,
+ *   selfNodeHash: string,
+ *   inRoomNodeHashes?: Set<string> | string[] 群内在线 node_id；有则优先，仅全不可达时用 explore 中非房内节点
+ *   hintSources?: Map<string, string> explore 节点来源（用于配额）
+ * }} opts 选取参数（roster、peers、rep、limits、selfNodeHash）
+ * @returns {string[]} 目标 Trystero 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 : [])
+	const onlineAll = roster.filter(
+		rosterEntry => rosterEntry.peerId
+			&& rosterEntry.remoteNodeHash
+			&& rosterEntry.remoteNodeHash !== selfNodeHash
+			&& !blocked.has(rosterEntry.remoteNodeHash),
+	)
+	const onlineInRoom = roomSet.size
+		? onlineAll.filter(rosterEntry => roomSet.has(rosterEntry.remoteNodeHash))
+		: onlineAll
+	const online = onlineInRoom.length ? onlineInRoom : onlineAll
+	if (!online.length) return []
+
+	const peerIdByNodeHash = new Map(online.map(rosterEntry => [rosterEntry.remoteNodeHash, rosterEntry.peerId]))
+	const trustedSet = new Set(peers.trustedPeers.filter(nodeHash => peerIdByNodeHash.has(nodeHash)))
+	const exploreSet = new Set(peers.explorePeers.filter(nodeHash => peerIdByNodeHash.has(nodeHash) && !trustedSet.has(nodeHash)))
+
+	const outPeerIds = new Set()
+	/**
+	 * @param {string} nodeHash 远端节点 hash
+	 */
+	const pushNode = nodeHash => {
+		const peerId = peerIdByNodeHash.get(nodeHash)
+		if (peerId) outPeerIds.add(peerId)
+	}
+
+	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)) {
+		if (outPeerIds.size >= limits.maxPeers) break
+		pushNode(nodeId)
+	}
+
+	const exploreArray = [...exploreSet]
+	for (const nodeId of selectExploreWithSourceQuota(exploreArray, hintSources, limits.exploreSlots)) {
+		if (outPeerIds.size >= limits.maxPeers) break
+		pushNode(nodeId)
+	}
+
+	const remainingNodeHashes = [...peerIdByNodeHash.keys()]
+		.filter(nodeHash => !trustedSet.has(nodeHash) && !exploreSet.has(nodeHash))
+		.sort((a, b) => repScore(b, rep) - repScore(a, rep))
+	for (const nodeHash of remainingNodeHashes) {
+		if (outPeerIds.size >= limits.maxPeers) break
+		pushNode(nodeHash)
+	}
+
+	return [...outPeerIds].slice(0, limits.maxPeers)
+}
+
+/**
+ * 从群成员集合选出应主动建链的 nodeHash（top-K 信任 + M 随机 explore + 强制锚点必连）。
+ * 与 selectPeerIdsFromPool 不同：候选是"已知成员 nodeHash"（未必在线），输出用于 ensureLinkToNode 的 nodeHash。
+ * 这让大群不再全网状 autoconnect，而是每节点只连少数信任节点 + 随机若干条以保图连通。
+ *
+ * @param {{
+ *   members: Iterable<string>,
+ *   selfNodeHash: string,
+ *   rep: { byNodeHash?: Record<string, { score?: number, quarantinedUntil?: number }> },
+ *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[], hintSources?: Map<string, string> },
+ *   limits: ReturnType<typeof resolveFederationPoolLimits>,
+ *   anchors?: Iterable<string>,
+ * }} opts 选取参数（members、selfNodeHash、rep、peers、limits、anchors）
+ * @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 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 chosen = new Set(forced)
+	// trusted 槽只从非锚点候选填：既有 trusted 优先保留，再按信誉补至 trustedSlots。
+	const nonForced = ranked.filter(id => !chosen.has(id))
+	for (const id of mergeTrustedWithAnchors(peers?.trustedPeers || [], nonForced, limits))
+		chosen.add(id)
+	const remaining = ranked.filter(id => !chosen.has(id))
+	for (const id of selectExploreWithSourceQuota(remaining, peers?.hintSources, limits.exploreSlots))
+		chosen.add(id)
+	return [...chosen]
+}
+
+/**
+ * 将新 PEX 节点线索合并进 explore 池，并按信誉重新填充 trusted 槽。
+ * 纯计算版本，不含 I/O：接受 peers 对象，返回新对象。
+ *
+ * @param {{
+ *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[] },
+ *   rep: { byNodeHash?: Record<string, { score?: number }> },
+ *   hints: string[],
+ *   limits: ReturnType<typeof resolveFederationPoolLimits>,
+ * }} opts 合并参数（peers、rep、hints、limits）
+ * @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),
+	)]
+	const explore = new Set(peers.explorePeers)
+	for (const id of ids)
+		if (!peers.blockedPeers.includes(id)) explore.add(id)
+	const newExplorePeers = [...explore].slice(-500)
+	const ranked = [...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, ranked, limits, peers.blockedPeers),
+		explorePeers: newExplorePeers,
+	}
+}
+
+/**
+ * 从 roster 观测中更新 explore 池并重新填充 trusted 槽（纯计算版本）。
+ *
+ * @param {{
+ *   peers: { trustedPeers: string[], explorePeers: string[], blockedPeers: string[] },
+ *   rep: { byNodeHash?: Record<string, { score?: number }> },
+ *   roster: Array<{ remoteNodeHash?: string }>,
+ *   limits: ReturnType<typeof resolveFederationPoolLimits>,
+ * }} opts roster 更新参数（peers、rep、roster、limits）
+ * @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,
+	}
+}
+
+/**
+ * 稀疏连接池：优先 trusted，再 explore，再其余在线节点。
+ * @param {string} groupId 群
+ * @param {{ peerId: string, remoteNodeHash?: string }[]} roster Trystero 在线表
+ * @param {object} groupSettings 物化群设置
+ * @param {string} selfNodeHash 本机 node_id
+ * @returns {string[]} 目标 Trystero 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,
+		hintSources: peers.hintSources,
+	})
+}
+
+/**
+ * 合并 PEX 提示并提升长期高信誉节点为 trusted。
+ * @param {string} groupId 群
+ * @param {string[]} hints 节点 id 列表
+ * @param {object} groupSettings 群设置
+ * @returns {void}
+ */
+export function mergePexNodeHints(groupId, hints, groupSettings) {
+	const limits = resolveFederationPoolLimits(groupSettings)
+	const peers = loadPeerPoolView(groupId)
+	const rep = loadReputation()
+	const { trustedPeers, explorePeers } = applyPexHints({ peers, rep, hints, limits })
+	mergeNetworkPeerPools({ trustedPeers, explorePeers })
+}
+
+/**
+ * roster 观测：将在线节点并入 explore，并按信誉填充 trusted 槽位。
+ * @param {string} groupId 群
+ * @param {{ remoteNodeHash?: string }[]} roster 在线表
+ * @param {object} groupSettings 群设置
+ * @returns {void}
+ */
+export function reconcilePeerPoolFromRoster(groupId, roster, groupSettings) {
+	if (!roster.length) return
+	const limits = resolveFederationPoolLimits(groupSettings)
+	const peers = loadPeerPoolView(groupId)
+	const rep = loadReputation()
+	const { trustedPeers, explorePeers } = applyRosterToPeerPool({ peers, rep, roster, limits })
+	mergeNetworkPeerPools({ trustedPeers, explorePeers })
+}

package/transport/remote_user_room.mjs

@@ -0,0 +1,109 @@
+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'
+
+
+/**
+ * @typedef {{
+ *   roomSlot: import('../registries/room_provider.mjs').FederationRoomSlot
+ *   leave: () => void | Promise<void>
+ * }} RemoteUserRoomSlot
+ */
+
+/** @type {Map<string, RemoteUserRoomSlot | null>} nodeHash → slot（null 表示加入失败/进行中） */
+const slots = new Map()
+/** @type {Map<string, Promise<RemoteUserRoomSlot | null>>} nodeHash → 进行中的 promise */
+const inflights = new Map()
+
+registerFederationRoomProvider('remote-user-room', () => {
+	return [...slots.values()]
+		.filter(Boolean)
+		.map(s => s.roomSlot)
+})
+
+/**
+ * 加入目标节点的用户房间（幂等）。
+ * @param {string} username 本地 replica 用户名
+ * @param {string} targetNodeHash 目标节点 64 hex
+ * @returns {Promise<RemoteUserRoomSlot | null>} 房间槽
+ */
+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 task = (async () => {
+		try {
+			if (!await ensureLinkToNode(key)) {
+				slots.set(key, null)
+				return null
+			}
+
+			/** @type {import('../registries/room_provider.mjs').FederationRoomSlot} */
+			const roomSlot = {
+				groupId: USER_ROOM_SCOPE,
+				/**
+				 * 返回远端用户房间 roster（链路存在时含目标节点）。
+				 * @returns {Array<{ peerId: string, remoteNodeHash: string }>} roster 列表
+				 */
+				getRoster: () => getLink(key) ? [{ peerId: key, remoteNodeHash: key }] : [],
+				/**
+				 * 按 nodeHash 查找 peer id。
+				 * @param {string} nh 目标节点 64 hex
+				 * @returns {string | null} 对端 id；无链路时为 null
+				 */
+				getPeerIdByNodeHash: nh => getLink(nh) ? String(nh) : null,
+				/**
+				 * 经 node scope 向远端 peer 发送 action。始终走当前规范链路（`getLink`），
+				 * 因为 glare 双 PC 择一后最初返回的链路可能已被关闭，规范链在 registry 内。
+				 * @param {string} peerId 目标 peer id
+				 * @param {string} actionName action 名称
+				 * @param {unknown} payload 载荷
+				 * @returns {void}
+				 */
+				sendToPeer(peerId, actionName, payload) {
+					void getLink(key)?.send({ scope: 'node', action: String(actionName), payload }).catch(() => { })
+				},
+			}
+
+			const slot = {
+				roomSlot,
+				/**
+				 * 关闭远端用户房间链路。
+				 * @returns {Promise<void>} 关闭完成
+				 */
+				leave() { return closeLink(key, 'remote-user-room-release') },
+			}
+			slots.set(key, slot)
+			invalidateTrustGraphCache()
+			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)
+		}
+	})()
+
+	inflights.set(key, task)
+	return await task
+}
+
+/**
+ * 释放目标节点的远端用户房间连接。
+ * @param {string} targetNodeHash 目标节点 64 hex
+ * @returns {void}
+ */
+export function releaseRemoteUserRoom(targetNodeHash) {
+	const key = targetNodeHash.toLowerCase()
+	const slot = slots.get(key)
+	if (slot) void Promise.resolve(slot.leave()).catch(() => { })
+	slots.delete(key)
+}

package/transport/room_scopes.mjs

@@ -0,0 +1,2 @@
+/** user room 在 trust graph / room provider 中的 scope id */
+export const USER_ROOM_SCOPE = 'user-room'

package/transport/room_wire_action.mjs

@@ -0,0 +1,19 @@
+/**
+ * 将 room 的 wire action 绑定到 senderRegistry。
+ * @param {object} roomContext 房间上下文（含 wireActions 与 senderRegistry）
+ * @param {string} name action 名称
+ * @returns {{ send: Function, on: (handler: Function) => void }} 发送函数与注册回调
+ */
+export function wireAction(roomContext, name) {
+	const send = roomContext.wireActions.sender(name)
+	roomContext.senderRegistry.set(name, send)
+	return {
+		send,
+		/**
+		 * 注册该 action 的入站 handler。
+		 * @param {Function} handler 入站回调
+		 * @returns {void}
+		 */
+		on: handler => { roomContext.wireActions.on(name, handler) },
+	}
+}