@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/transport/link_registry.mjs

@@ -2,21 +2,21 @@ import { Buffer } from 'node:buffer'
 
 import { compareHex64Asc, normalizeHex64 } from '../core/hexIds.mjs'
 import { keyPairFromSeed } from '../crypto/crypto.mjs'
-import { noteAdvertPeerHints } from '../discovery/advert_peer_hints.mjs'
-import { subscribeTopic } from '../discovery/index.mjs'
-import { verifySignedAdvert } from '../link/handshake.mjs'
+import { watchVerifiedNodeAdvert, setDiscoveryLinkDialer, prepareConnectToNode } from '../discovery/index.mjs'
 import { listLinkProviders } from '../link/providers/index.mjs'
 import { ensureNodeSeed, getNodeHash } from '../node/identity.mjs'
+import { nodeDebug, shortHash } from '../node/log.mjs'
+import { loadPeerPoolView } from '../node/network.mjs'
 import { createOverlayRouter } from '../overlay/index.mjs'
+import { emitSafe } from '../utils/emit_safe.mjs'
 import { createLruMap } from '../utils/lru.mjs'
 
+import { applyAdvertPeerHints } from './advert_ingest.mjs'
 import { DEFAULT_ICE_SERVERS } from './ice_servers.mjs'
+import { createMeshKeepalive } from './mesh_keepalive.mjs'
 import { createOfferAnswerDial } from './offer_answer.mjs'
+import { pickMeshEvictionVictim } from './peer_pool.mjs'
 import { createRuntimeBootstrap } from './runtime_bootstrap.mjs'
-import {
-	decryptSignalPacket,
-	nodeRendezvousTopic,
-} from './signal_crypto.mjs'
 
 /**
  * 解析或从节点种子推导本地身份。
@@ -63,15 +63,23 @@ function subscribeBucket(buckets, key, listener) {
  * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array }} [options.localIdentity] 本地身份
  * @param {RTCConfiguration['iceServers']} [options.iceServers] ICE 服务器列表（包内 webrtc provider 使用）
  * @param {number} [options.maxActive] 最大并发活跃链路数
+ * @param {boolean} [options.meshKeepalive=true] 是否启用 mesh 保活（N/K 扫描拨号）
  * @param {boolean} [options.autoRegisterDiscoveryProviders] 是否自动注册 discovery provider
  * @param {boolean} [options.autoRegisterLinkProviders] 是否自动注册内置 link provider
  * @returns {object} link registry 接口（对上层即 fount 网络：ensure/send/subscribe，无传输类型）
  */
 export function createLinkRegistry(options = {}) {
 	const localIdentity = resolveLocalIdentity(options.localIdentity)
-	const iceServers = options.iceServers?.length ? options.iceServers : DEFAULT_ICE_SERVERS
-	const maxActive = Math.max(4, Number(options.maxActive) || 32)
-	const selfTopic = nodeRendezvousTopic(localIdentity.nodeHash)
+	let iceServers = options.iceServers?.length ? options.iceServers : DEFAULT_ICE_SERVERS
+	let maxActive = Math.max(4, Number(options.maxActive) || 32)
+	const savedMaxActive = maxActive
+	const meshKeepaliveEnabled = options.meshKeepalive !== false
+	/** @type {((nodeHash: string) => number) | null} */
+	let priorityWeightFunction = null
+	/** @type {Set<string>} */
+	let exploreLinkHashes = new Set()
+	/** @type {ReturnType<typeof createMeshKeepalive> | null} */
+	let meshKeepalive = null
 	/** @type {Map<string, object>} */
 	const links = new Map()
 	/** @type {Map<string, Promise<object | null>>} */
@@ -104,8 +112,8 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {boolean} 候选链应保留为规范链时 true
 	 */
 	function linkIsPreferred(link, remoteNodeHash, against = null) {
-		const level = Number(link.level) || 0
-		const againstLevel = Number(against?.level) || 0
+		const level = link.level || 0
+		const againstLevel = against?.level || 0
 		if (against && level !== againstLevel) return level > againstLevel
 		const cmp = compareHex64Asc(localIdentity.nodeHash, remoteNodeHash)
 		return link.initiator ? cmp < 0 : cmp > 0
@@ -125,8 +133,7 @@ export function createLinkRegistry(options = {}) {
 			const wasCanonical = links.get(remoteNodeHash) === link
 			if (!wasCanonical) return
 			links.delete(remoteNodeHash)
-			for (const listener of linkDownListeners)
-				try { listener(remoteNodeHash, reason) } catch { /* ignore */ }
+			emitSafe(linkDownListeners, remoteNodeHash, reason)
 		})
 	}
 
@@ -140,15 +147,14 @@ export function createLinkRegistry(options = {}) {
 		const normalized = normalizeHex64(remoteNodeHash)
 		const existing = links.get(normalized)
 		if (existing && existing !== candidate && !linkIsPreferred(candidate, normalized, existing)) {
-			await candidate.close(Number(candidate.level) !== Number(existing.level) ? 'provider-loser' : 'glare-loser')
+			await candidate.close(candidate.level !== existing.level ? 'provider-loser' : 'glare-loser')
 			return
 		}
 		links.set(normalized, candidate)
 		wireLink(normalized, candidate)
 		if (existing && existing !== candidate)
-			await existing.close(Number(candidate.level) !== Number(existing.level) ? 'provider-replaced' : 'glare-replaced')
-		for (const listener of linkUpListeners)
-			try { listener(normalized, candidate) } catch { /* ignore */ }
+			await existing.close(candidate.level !== existing.level ? 'provider-replaced' : 'glare-replaced')
+		emitSafe(linkUpListeners, normalized, candidate)
 	}
 
 	/**
@@ -173,10 +179,13 @@ export function createLinkRegistry(options = {}) {
 
 	const bootstrap = createRuntimeBootstrap({
 		localIdentity,
-		selfTopic,
 		autoRegisterDiscoveryProviders: options.autoRegisterDiscoveryProviders !== false,
 		autoRegisterLinkProviders: options.autoRegisterLinkProviders !== false,
 		onInboundLink,
+		/**
+		 * @param {Uint8Array} bytes 入站加密信令
+		 * @returns {Promise<void>}
+		 */
 		handleIncomingSignal: bytes => handleIncomingSignal(bytes),
 	})
 
@@ -186,35 +195,41 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {number} 权重值
 	 */
 	function scopeWeight(remoteNodeHash) {
-		let weight = 0
+		let weight = priorityWeightFunction?.(remoteNodeHash) ?? 0
 		for (const hashes of scopeInterests.values())
 			if (hashes.has(remoteNodeHash)) weight++
 		return weight
 	}
 
 	/**
-	 * 超出 maxActive 时驱逐权重最低的链路。
+	 * 超出 maxActive 时驱逐：探索链优先于熟人/scope 权重。
 	 * @returns {Promise<void>}
 	 */
 	async function trimToBudget() {
 		if (links.size < maxActive) return
-		const candidates = [...links.entries()]
-			.sort((left, right) => scopeWeight(left[0]) - scopeWeight(right[0]) || compareHex64Asc(left[0], right[0]))
-		const victim = candidates[0]
-		if (victim) await victim[1].close('budget-evict')
+		const peers = loadPeerPoolView()
+		const victimHash = pickMeshEvictionVictim(
+			[...links.keys()],
+			exploreLinkHashes,
+			peers.trustedPeers,
+			scopeWeight,
+		)
+		const victimLink = victimHash ? links.get(victimHash) : null
+		if (victimLink) await victimLink.close('budget-evict')
 	}
 
-	;({ handleIncomingSignal, dialOfferAnswer } = createOfferAnswerDial({
+	; ({ handleIncomingSignal, dialOfferAnswer } = createOfferAnswerDial({
 		localIdentity,
-		iceServers,
-		selfTopic,
+		/**
+		 * @returns {RTCConfiguration['iceServers']} 当前 ICE 服务器列表
+		 */
+		get iceServers() { return iceServers },
 		signalSessions,
 		registerResolvedLink,
 		trimToBudget,
 		/**
-		 * 读取当前规范链。
-		 * @param {string} remoteNodeHash 远端节点 64 hex
-		 * @returns {object | null | undefined} 规范链实例
+		 * @param {string} remoteNodeHash 远端 nodeHash
+		 * @returns {object | null} 已有规范链路
 		 */
 		getCanonicalLink: remoteNodeHash => links.get(normalizeHex64(remoteNodeHash)),
 	}))
@@ -251,33 +266,100 @@ export function createLinkRegistry(options = {}) {
 		if (links.has(normalized)) return links.get(normalized)
 		if (inflights.has(normalized)) return await inflights.get(normalized)
 		const task = (async () => {
+			nodeDebug('p2p:dial start', { peer: shortHash(normalized) })
+			await prepareConnectToNode(normalized)
 			const providers = listLinkProviders()
 			for (const provider of providers)
 				try {
 					if (typeof provider.canReach === 'function') {
 						const reachable = await Promise.resolve(provider.canReach({ nodeHash: normalized }))
-						if (!reachable) continue
+						if (!reachable) {
+							nodeDebug('p2p:dial skip', { peer: shortHash(normalized), provider: provider.id, reason: 'canReach=false' })
+							continue
+						}
 					}
 					if (typeof provider.isAvailable === 'function') {
 						const available = await Promise.resolve(provider.isAvailable())
-						if (!available) continue
+						if (!available) {
+							nodeDebug('p2p:dial skip', { peer: shortHash(normalized), provider: provider.id, reason: 'isAvailable=false' })
+							continue
+						}
 					}
+					nodeDebug('p2p:dial try', { peer: shortHash(normalized), provider: provider.id })
 					if (provider.caps?.needsOfferAnswer) {
 						const link = await dialOfferAnswer(provider, normalized)
-						if (link) return link
+						if (link) {
+							nodeDebug('p2p:dial ok', { peer: shortHash(normalized), provider: provider.id })
+							return link
+						}
+						nodeDebug('p2p:dial miss', { peer: shortHash(normalized), provider: provider.id })
 						continue
 					}
 					const link = await dialProvider(provider, normalized)
-					if (link) return link
+					if (link) {
+						nodeDebug('p2p:dial ok', { peer: shortHash(normalized), provider: provider.id })
+						return link
+					}
+					nodeDebug('p2p:dial miss', { peer: shortHash(normalized), provider: provider.id })
+				}
+				catch (error) {
+					nodeDebug('p2p:dial fail', {
+						peer: shortHash(normalized),
+						provider: provider.id,
+						err: String(error?.message || error),
+					})
 				}
-				catch { /* dial failed — try next provider */ }
 
+			nodeDebug('p2p:dial exhausted', { peer: shortHash(normalized) })
 			return null
 		})().finally(() => inflights.delete(normalized))
 		inflights.set(normalized, task)
 		return await task
 	}
 
+	meshKeepalive = createMeshKeepalive({
+		registry: {
+			localIdentity,
+			/**
+			 * @returns {Array<{ nodeHash: string, link: object }>} 当前链路列表
+			 */
+			listLinks: () => [...links.entries()].map(([nodeHash, link]) => ({ nodeHash, link })),
+			/**
+			 * @param {string} nodeHash 目标 nodeHash
+			 * @returns {object | null} 已有链路或 null
+			 */
+			getLink: nodeHash => links.get(normalizeHex64(nodeHash)) || null,
+			ensureLinkToNode: ensureDirectLinkToNode,
+			/**
+			 * @param {(nodeHash: string) => void} listener link up 回调
+			 * @returns {() => void} 取消订阅
+			 */
+			onLinkUp: listener => {
+				linkUpListeners.add(listener)
+				return () => linkUpListeners.delete(listener)
+			},
+			/**
+			 * @param {(nodeHash: string, reason: string) => void} listener link down 回调
+			 * @returns {() => void} 取消订阅
+			 */
+			onLinkDown: listener => {
+				linkDownListeners.add(listener)
+				return () => linkDownListeners.delete(listener)
+			},
+		},
+		enabled: meshKeepaliveEnabled,
+	})
+	exploreLinkHashes = meshKeepalive.exploreLinkHashes
+	setDiscoveryLinkDialer(ensureDirectLinkToNode)
+
+	/**
+	 *
+	 */
+	const ensureRuntimeWithMesh = async () => {
+		await bootstrap.ensureRuntime()
+		meshKeepalive?.start()
+	}
+
 	/**
 	 * 经已有直连发送 envelope。
 	 * @param {string} remoteNodeHash 远端节点 64 hex
@@ -318,6 +400,13 @@ export function createLinkRegistry(options = {}) {
 		return overlayRouter
 	}
 
+	/**
+	 * @returns {import('../overlay/index.mjs').OverlayRouter} overlay 路由器单例
+	 */
+	function ensureOverlayRouter() {
+		return getOverlayRouter()
+	}
+
 	/**
 	 * 经 overlay 多跳 relay envelope 到无直连的节点。
 	 * @param {string} remoteNodeHash 远端节点 64 hex
@@ -327,8 +416,9 @@ export function createLinkRegistry(options = {}) {
 	async function relayEnvelopeToNode(remoteNodeHash, envelope) {
 		if (!links.size || envelope?.scope === 'overlay') return false
 		try {
-			const path = await getOverlayRouter().discoverRoute(remoteNodeHash)
-			await getOverlayRouter().relay(path, envelope)
+			const overlay = getOverlayRouter()
+			const path = await overlay.discoverRoute(remoteNodeHash)
+			await overlay.relay(path, envelope)
 			return true
 		}
 		catch {
@@ -347,6 +437,17 @@ export function createLinkRegistry(options = {}) {
 			|| await relayEnvelopeToNode(remoteNodeHash, envelope)
 	}
 
+	/**
+	 * 同步结果直接返回；thenable 才 await（避免每条 envelope 造 microtask）。
+	 * @param {unknown} value 可能为 Promise 的返回值
+	 * @returns {Promise<unknown>} 已 resolve 的值
+	 */
+	async function maybeAwait(value) {
+		if (value != null && typeof /** @type {{ then?: unknown }} */ value.then === 'function')
+			return await value
+		return value
+	}
+
 	/**
 	 * 将入站 envelope 派发到 scope 监听器（经 authorizer 校验）。
 	 * @param {string} senderNodeHash 发送方节点 64 hex
@@ -355,16 +456,16 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {Promise<void>}
 	 */
 	async function dispatchEnvelope(senderNodeHash, envelope, link) {
-		const scope = String(envelope?.scope || '')
+		const scope = envelope.scope || ''
 		for (const [prefix, authorizer] of scopeAuthorizers.entries())
 			if (scope.startsWith(prefix)) {
-				const allowed = await Promise.resolve(authorizer(scope, senderNodeHash, envelope, link))
+				const allowed = await maybeAwait(authorizer(scope, senderNodeHash, envelope, link))
 				if (!allowed) return
 			}
 		for (const [prefix, listeners] of scopeListeners.entries())
 			if (scope.startsWith(prefix))
 				for (const listener of listeners)
-					await Promise.resolve(listener(senderNodeHash, envelope, link))
+					await maybeAwait(listener(senderNodeHash, envelope, link))
 	}
 
 	/**
@@ -374,7 +475,7 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {() => void} 取消订阅函数
 	 */
 	function subscribeScope(prefix, listener) {
-		return subscribeBucket(scopeListeners, String(prefix), listener)
+		return subscribeBucket(scopeListeners, prefix, listener)
 	}
 
 	/**
@@ -384,8 +485,8 @@ export function createLinkRegistry(options = {}) {
 	 * @returns {() => void} 取消注册函数
 	 */
 	function registerScopeAuthorizer(prefix, authorizer) {
-		scopeAuthorizers.set(String(prefix), authorizer)
-		return () => scopeAuthorizers.delete(String(prefix))
+		scopeAuthorizers.set(prefix, authorizer)
+		return () => scopeAuthorizers.delete(prefix)
 	}
 
 	return {
@@ -393,8 +494,55 @@ export function createLinkRegistry(options = {}) {
 		buildLocalAdvert: bootstrap.buildLocalAdvert,
 		lanTcpPort: bootstrap.lanTcpPort,
 		whenListening: bootstrap.whenListening,
-		ensureRuntime: bootstrap.ensureRuntime,
+		ensureRuntime: ensureRuntimeWithMesh,
+		reloadDiscoveryRelays: bootstrap.reloadDiscoveryRelays,
+		ensureOverlayRouter,
+		getOverlayRouter,
 		ensureLinkToNode: ensureDirectLinkToNode,
+		/**
+		 * 设置最大并发活跃链路数。
+		 * @param {number} value 最大并发活跃链路数
+		 * @returns {Promise<void>}
+		 */
+		async setMaxActive(value) {
+			maxActive = Math.max(4, Math.min(128, Math.floor(Number(value) || savedMaxActive)))
+			await trimToBudget()
+		},
+		/**
+		 * @returns {number} 当前 maxActive
+		 */
+		getMaxActive() {
+			return maxActive
+		},
+		/**
+		 * 设置 ICE 服务器列表。
+		 * @param {RTCConfiguration['iceServers']} servers ICE 列表
+		 * @returns {void}
+		 */
+		setIceServers(servers) {
+			iceServers = servers?.length ? servers : DEFAULT_ICE_SERVERS
+		},
+		/**
+		 * @returns {RTCConfiguration['iceServers']} 当前 ICE 服务器列表
+		 */
+		getIceServers() {
+			return iceServers
+		},
+		/**
+		 * infra/trim：额外优先级权重；null 清除。
+		 * @param {((nodeHash: string) => number) | null} weightFunction 额外 trim 权重；null 清除
+		 * @returns {void}
+		 */
+		setPriorityWeightFunction(weightFunction) {
+			priorityWeightFunction = typeof weightFunction === 'function' ? weightFunction : null
+		},
+		/**
+		 * @param {string} nodeHash - 节点 64-hex hash
+		 * @returns {number} 额外路由 trim 权重
+		 */
+		getPriorityWeight(nodeHash) {
+			return priorityWeightFunction?.(nodeHash) ?? 0
+		},
 		/**
 		 * 获取到指定节点的活跃链路。
 		 * @param {string} nodeHash 节点 64 hex
@@ -448,7 +596,7 @@ export function createLinkRegistry(options = {}) {
 		 * @returns {void}
 		 */
 		registerScopeInterest(scope, nodeHashes) {
-			scopeInterests.set(String(scope), new Set((Array.isArray(nodeHashes) ? nodeHashes : []).map(normalizeHex64).filter(Boolean)))
+			scopeInterests.set(scope, new Set((nodeHashes || []).map(normalizeHex64).filter(Boolean)))
 		},
 		/**
 		 * 释放 scope 兴趣。
@@ -456,26 +604,22 @@ export function createLinkRegistry(options = {}) {
 		 * @returns {void}
 		 */
 		releaseScopeInterest(scope) {
-			scopeInterests.delete(String(scope))
+			scopeInterests.delete(scope)
 		},
 		registerScopeAuthorizer,
 		subscribeScope,
 		/**
-		 * 订阅指定节点的 advert 广播。
+		 * 监听指定节点的 advert（per-hash，无 topic）。
 		 * @param {string} nodeHash 目标节点 64 hex
 		 * @param {(verifiedNodeHash: string, body: object) => void | Promise<void>} onAdvert advert 回调
-		 * @returns {Promise<() => void>} 取消订阅函数
+		 * @returns {Promise<() => void>} 取消函数
 		 */
-		async subscribeNodeAdvert(nodeHash, onAdvert) {
-			const topic = nodeRendezvousTopic(nodeHash)
-			return await subscribeTopic(topic, async (bytes, meta) => {
-				const packet = decryptSignalPacket(topic, bytes)
-				if (packet?.type !== 'advert') return
-				const verifiedNodeHash = await verifySignedAdvert(topic, packet.body)
-				if (!verifiedNodeHash) return
-				noteAdvertPeerHints(verifiedNodeHash, packet.body, meta)
+		async watchNodeAdvert(nodeHash, onAdvert) {
+			const hash = normalizeHex64(nodeHash)
+			return await watchVerifiedNodeAdvert(hash, async (verifiedNodeHash, body, meta) => {
+				applyAdvertPeerHints(verifiedNodeHash, body, meta)
 				recentAdverts.touch(verifiedNodeHash, Date.now())
-				await Promise.resolve(onAdvert(verifiedNodeHash, packet.body))
+				await Promise.resolve(onAdvert(verifiedNodeHash, body))
 			})
 		},
 		recentAdverts,
@@ -485,6 +629,8 @@ export function createLinkRegistry(options = {}) {
 		 * @returns {Promise<void>}
 		 */
 		async shutdown() {
+			await meshKeepalive?.stop()
+			setDiscoveryLinkDialer(null)
 			await bootstrap.shutdown()
 			overlayRouter?.close()
 			overlayRouter = null
@@ -499,84 +645,97 @@ export function createLinkRegistry(options = {}) {
 }
 
 let defaultRegistry = null
+/** @type {object | null} */
+let pendingRegistryOptions = null
 
 /**
- * 获取进程级默认 link registry 单例。
- * @returns {ReturnType<typeof createLinkRegistry>} 默认 registry
+ * 在首次 getLinkRegistry 前配置默认 registry 选项。
+ * @param {object} options createLinkRegistry 选项
+ * @returns {void}
  */
-export function getLinkRegistry() {
-	return defaultRegistry ||= createLinkRegistry()
+export function configureLinkRegistry(options = {}) {
+	if (defaultRegistry) throw new Error('p2p: configureLinkRegistry must run before getLinkRegistry')
+	pendingRegistryOptions = { ...pendingRegistryOptions, ...options }
 }
 
 /**
- * 默认 registry 的 ensureLinkToNode 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['ensureLinkToNode']>} 链路实例
- */
-export const ensureLinkToNode = (...args) => getLinkRegistry().ensureLinkToNode(...args)
-/**
- * 默认 registry 的 getLink 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['getLink']>} 链路实例
- */
-export const getLink = (...args) => getLinkRegistry().getLink(...args)
-/**
- * 默认 registry 的 listLinks 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['listLinks']>} 链路列表
+ * @returns {void}
  */
-export const listLinks = (...args) => getLinkRegistry().listLinks(...args)
-/**
- * 默认 registry 的 closeLink 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['closeLink']>} 关闭完成
- */
-export const closeLink = (...args) => getLinkRegistry().closeLink(...args)
-/**
- * 默认 registry 的 sendToNodeLink 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['sendToNodeLink']>} 是否成功
- */
-export const sendToNodeLink = (...args) => getLinkRegistry().sendToNodeLink(...args)
-/**
- * 默认 registry 的 relayEnvelopeToNode 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['relayEnvelopeToNode']>} 是否成功
- */
-export const relayEnvelopeToNode = (...args) => getLinkRegistry().relayEnvelopeToNode(...args)
-/**
- * 默认 registry 的 onLinkUp 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['onLinkUp']>} 取消订阅函数
- */
-export const onLinkUp = (...args) => getLinkRegistry().onLinkUp(...args)
-/**
- * 默认 registry 的 onLinkDown 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['onLinkDown']>} 取消订阅函数
- */
-export const onLinkDown = (...args) => getLinkRegistry().onLinkDown(...args)
+export function resetLinkRegistryForTests() {
+	defaultRegistry = null
+	pendingRegistryOptions = null
+}
+
 /**
- * 默认 registry 的 registerScopeInterest 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['registerScopeInterest']>} 无返回值
+ * 默认 registry 尚未创建时暂存的 scope authorizer 条目。
+ * 注册阶段不应触发 createLinkRegistry / resolveLocalIdentity；绑定在 getLinkRegistry flush 时完成。
+ * @type {Array<{ prefix: string, authorizer: Function, unregister: (() => void) | null }>}
  */
-export const registerScopeInterest = (...args) => getLinkRegistry().registerScopeInterest(...args)
+const pendingScopeAuthorizers = []
+
 /**
- * 默认 registry 的 releaseScopeInterest 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['releaseScopeInterest']>} 无返回值
+ * 获取进程级默认 link registry 单例。
+ * @returns {ReturnType<typeof createLinkRegistry>} 默认 registry
  */
-export const releaseScopeInterest = (...args) => getLinkRegistry().releaseScopeInterest(...args)
+export function getLinkRegistry() {
+	if (defaultRegistry) return defaultRegistry
+	defaultRegistry = createLinkRegistry(pendingRegistryOptions || {})
+	pendingRegistryOptions = null
+	for (const entry of pendingScopeAuthorizers)
+		entry.unregister = defaultRegistry.registerScopeAuthorizer(entry.prefix, entry.authorizer)
+	pendingScopeAuthorizers.length = 0
+	return defaultRegistry
+}
+
 /**
- * 默认 registry 的 registerScopeAuthorizer 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['registerScopeAuthorizer']>} 取消注册函数
+ * 默认 registry 方法代理。
+ * @param {string} name registry 方法名
+ * @returns {(...methodArguments: unknown[]) => unknown} 绑定到 getLinkRegistry()[name] 的函数
  */
-export const registerScopeAuthorizer = (...args) => getLinkRegistry().registerScopeAuthorizer(...args)
+const bindRegistryMethod = name => (...methodArguments) => getLinkRegistry()[name](...methodArguments)
+
+/** 确保 overlay 路由器已创建。 @type {(...methodArguments: unknown[]) => unknown} */
+export const ensureOverlayRouter = bindRegistryMethod('ensureOverlayRouter')
+/** 热重载 discovery relay 配置。 @type {(...methodArguments: unknown[]) => unknown} */
+export const reloadDiscoveryRelays = bindRegistryMethod('reloadDiscoveryRelays')
+/** 确保到 nodeHash 的活跃链路。 @type {(...methodArguments: unknown[]) => unknown} */
+export const ensureLinkToNode = bindRegistryMethod('ensureLinkToNode')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const getLink = bindRegistryMethod('getLink')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const listLinks = bindRegistryMethod('listLinks')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const closeLink = bindRegistryMethod('closeLink')
+/** 经活跃链路向节点发送 envelope。 @type {(...methodArguments: unknown[]) => unknown} */
+export const sendToNodeLink = bindRegistryMethod('sendToNodeLink')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const relayEnvelopeToNode = bindRegistryMethod('relayEnvelopeToNode')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const onLinkUp = bindRegistryMethod('onLinkUp')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const onLinkDown = bindRegistryMethod('onLinkDown')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const registerScopeInterest = bindRegistryMethod('registerScopeInterest')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const releaseScopeInterest = bindRegistryMethod('releaseScopeInterest')
+/** @type {(...methodArguments: unknown[]) => unknown} */
+export const subscribeScope = bindRegistryMethod('subscribeScope')
+
 /**
- * 默认 registry 的 subscribeScope 代理。
- * @param {...any} args 转发参数
- * @returns {ReturnType<ReturnType<typeof createLinkRegistry>['subscribeScope']>} 取消订阅函数
+ * 注册默认 registry 的 scope authorizer。
+ * 不急切创建 registry（不必 resolveLocalIdentity）；首次 getLinkRegistry 时 flush。
+ * @param {string} prefix scope 前缀
+ * @param {Function} authorizer 校验函数
+ * @returns {() => void} 取消注册函数
  */
-export const subscribeScope = (...args) => getLinkRegistry().subscribeScope(...args)
+export function registerScopeAuthorizer(prefix, authorizer) {
+	if (defaultRegistry) return defaultRegistry.registerScopeAuthorizer(prefix, authorizer)
+
+	const entry = { prefix, authorizer, unregister: null }
+	pendingScopeAuthorizers.push(entry)
+	return () => {
+		const index = pendingScopeAuthorizers.indexOf(entry)
+		if (index !== -1) pendingScopeAuthorizers.splice(index, 1)
+		entry.unregister?.()
+	}
+}