@steve02081504/fount-p2p 0.0.5 → 0.0.6

package/link/link.mjs

@@ -73,27 +73,27 @@ function formatErrorReason(error) {
 
 /**
  * 建立 P2P link：WebRTC 双通道、握手、分帧收发与心跳。
- * @param {object} opts link 配置
- * @param {string | null} [opts.nodeHash] 期望的对端 nodeHash，省略则不校验
- * @param {boolean} opts.initiator 是否为连接发起方
- * @param {{ send: (message: unknown) => void | Promise<void>, onRemote: (handler: (message: unknown) => void) => (() => void) | void }} opts.signal 信令收发接口
- * @param {RTCConfiguration['iceServers']} [opts.iceServers] ICE 服务器列表
- * @param {number} [opts.heartbeatMs] 心跳间隔（毫秒）
- * @param {number} [opts.idleTimeoutMs] 无入站流量超时（毫秒）
- * @param {number} [opts.handshakeTimeoutMs] 握手超时（毫秒）
- * @param {{ RTCPeerConnection: typeof RTCPeerConnection } | null} [opts.rtc] RTC 构造器，省略则加载 polyfill
- * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array, nonce?: string } | null} [opts.localIdentity] 本地握手身份
- * @returns {Promise<{ ready: Promise<void>, get nodeHash(): string | null, send: (envelope: { scope: string, action: string, payload: unknown }) => Promise<boolean>, onEnvelope: (cb: (envelope: { scope: string, action: string, payload: unknown }, remoteNodeHash: string) => void) => () => void, onDown: (cb: (reason: string) => void) => () => void, close: (reason?: string) => Promise<void>, stats: () => object }>} link 句柄
+ * @param {object} options link 配置
+ * @param {string | null} [options.nodeHash] 期望的对端 nodeHash，省略则不校验
+ * @param {boolean} options.initiator 是否为连接发起方
+ * @param {{ send: (message: unknown) => void | Promise<void>, onRemote: (handler: (message: unknown) => void) => (() => void) | void }} options.signal 信令收发接口
+ * @param {RTCConfiguration['iceServers']} [options.iceServers] ICE 服务器列表
+ * @param {number} [options.heartbeatMs] 心跳间隔（毫秒）
+ * @param {number} [options.idleTimeoutMs] 无入站流量超时（毫秒）
+ * @param {number} [options.handshakeTimeoutMs] 握手超时（毫秒）
+ * @param {{ RTCPeerConnection: typeof RTCPeerConnection } | null} [options.rtc] RTC 构造器，省略则加载 polyfill
+ * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array, nonce?: string } | null} [options.localIdentity] 本地握手身份
+ * @returns {Promise<{ ready: Promise<void>, get nodeHash(): string | null, send: (envelope: { scope: string, action: string, payload: unknown }) => Promise<boolean>, onEnvelope: (callback: (envelope: { scope: string, action: string, payload: unknown }, remoteNodeHash: string) => void) => () => void, onDown: (callback: (reason: string) => void) => () => void, close: (reason?: string) => Promise<void>, stats: () => object }>} link 句柄
  */
-export async function createLink(opts) {
-	const heartbeatMs = Number(opts.heartbeatMs) || ms('15s')
-	const idleTimeoutMs = Number(opts.idleTimeoutMs) || ms('45s')
-	const handshakeTimeoutMs = Number(opts.handshakeTimeoutMs) || ms('10s')
+export async function createLink(options) {
+	const heartbeatMs = Number(options.heartbeatMs) || ms('15s')
+	const idleTimeoutMs = Number(options.idleTimeoutMs) || ms('45s')
+	const handshakeTimeoutMs = Number(options.handshakeTimeoutMs) || ms('10s')
 	const channelOpenTimeoutMs = Math.max(handshakeTimeoutMs, ms('30s'))
 	const trickleIceOff = getSignalingRuntimeConfig().trickleIceOff === true
-	const rtc = opts.rtc ?? await loadNodeRtcPolyfill()
-	const pc = new rtc.RTCPeerConnection(opts.iceServers?.length ? { iceServers: opts.iceServers } : undefined)
-	const targetNodeHash = normalizeHex64(opts.nodeHash || '')
+	const rtc = options.rtc ?? await loadNodeRtcPolyfill()
+	const pc = new rtc.RTCPeerConnection(options.iceServers?.length ? { iceServers: options.iceServers } : undefined)
+	const targetNodeHash = normalizeHex64(options.nodeHash || '')
 	const remoteSignalQueue = []
 	const seenRemoteSignals = createLruMap(1024)
 	let remoteDescriptionSet = false
@@ -142,7 +142,7 @@ export async function createLink(opts) {
 	 * @returns {Promise<void>}
 	 */
 	async function sendSignal(message) {
-		await Promise.resolve(opts.signal.send(message))
+		await Promise.resolve(options.signal.send(message))
 	}
 
 	/**
@@ -185,7 +185,7 @@ export async function createLink(opts) {
 		const fingerprint = localFingerprint()
 		if (!fingerprint) return
 		authSent = true
-		await sendRawControl(await buildAuth(remoteHello.nonce, fingerprint, opts.localIdentity ?? {}))
+		await sendRawControl(await buildAuth(remoteHello.nonce, fingerprint, options.localIdentity ?? {}))
 	}
 
 	/**
@@ -446,7 +446,7 @@ export async function createLink(opts) {
 		if (!helloSent) {
 			handshakeTimer = setTimeout(() => { void close('handshake-timeout') }, handshakeTimeoutMs)
 			helloSent = true
-			localHello = buildHello(opts.localIdentity ?? {})
+			localHello = buildHello(options.localIdentity ?? {})
 			await sendRawControl(localHello)
 		}
 		await maybeSendAuth()
@@ -507,7 +507,7 @@ export async function createLink(opts) {
 		emitListeners(downListeners, reason)
 	}
 
-	unlistenRemote = opts.signal.onRemote(message => {
+	unlistenRemote = options.signal.onRemote(message => {
 		void handleRemoteSignal(message).catch(error => close(`signal-error:${formatErrorReason(error)}`))
 	}) ?? null
 
@@ -535,7 +535,7 @@ export async function createLink(opts) {
 		}
 	}
 
-	if (opts.initiator) {
+	if (options.initiator) {
 		await attachChannel(pc.createDataChannel(CHANNEL_CONTROL))
 		await attachChannel(pc.createDataChannel(CHANNEL_BULK))
 		const offer = await pc.createOffer()
@@ -559,25 +559,25 @@ export async function createLink(opts) {
 		 * 本端是否为连接发起方。
 		 * @returns {boolean} 发起方标志
 		 */
-		get initiator() { return !!opts.initiator },
+		get initiator() { return !!options.initiator },
 		send,
 		/**
 		 * 订阅业务 envelope 入站。
-		 * @param {(envelope: { scope: string, action: string, payload: unknown }, remoteNodeHash: string) => void} cb 回调
+		 * @param {(envelope: { scope: string, action: string, payload: unknown }, remoteNodeHash: string) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onEnvelope(cb) {
-			envelopeListeners.add(cb)
-			return () => envelopeListeners.delete(cb)
+		onEnvelope(callback) {
+			envelopeListeners.add(callback)
+			return () => envelopeListeners.delete(callback)
 		},
 		/**
 		 * 订阅 link 断开事件。
-		 * @param {(reason: string) => void} cb 回调
+		 * @param {(reason: string) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onDown(cb) {
-			downListeners.add(cb)
-			return () => downListeners.delete(cb)
+		onDown(callback) {
+			downListeners.add(callback)
+			return () => downListeners.delete(callback)
 		},
 		close,
 		/**
@@ -597,7 +597,7 @@ export async function createLink(opts) {
 				ready,
 				nodeHash: remoteNodeHash,
 				targetNodeHash: targetNodeHash || null,
-				initiator: !!opts.initiator,
+				initiator: !!options.initiator,
 				connectionState: pc.connectionState,
 				iceConnectionState: pc.iceConnectionState,
 				lastInboundAt,

package/mailbox/deliver_or_store.mjs

@@ -59,26 +59,26 @@ async function resolveRouting(username) {
 
 /**
  * @param {string} username 副本用户名（trust graph 投递上下文）
- * @param {object} opts 投递选项
+ * @param {object} options 投递选项
  * @returns {Promise<{ stored: boolean, delivered: boolean, relayed: number }>} 存转结果
  */
-export async function deliverOrStoreMailboxPut(username, opts) {
+export async function deliverOrStoreMailboxPut(username, options) {
 	const routing = await resolveRouting(username)
-	const toPubKeyHash = normalizeHex64(opts.toPubKeyHash)
+	const toPubKeyHash = normalizeHex64(options.toPubKeyHash)
 	if (!toPubKeyHash) return { stored: false, delivered: false, relayed: 0 }
-	const hop = normalizeMailboxHop(opts.hop)
+	const hop = normalizeMailboxHop(options.hop)
 	if (hop >= routing.maxHop) return { stored: false, delivered: false, relayed: 0 }
 	const tier = mailboxTierFromHop(hop)
 	const nodeHash = getNodeHash()
 	const record = {
-		...opts.record,
+		...options.record,
 		toPubKeyHash,
 		hop,
 		tier,
-		fromNodeHash: opts.record?.fromNodeHash || nodeHash,
+		fromNodeHash: options.record?.fromNodeHash || nodeHash,
 	}
 	const stored = await storeMailboxRecord(record)
-	const toNodeHash = opts.toNodeHash?.trim().toLowerCase()
+	const toNodeHash = options.toNodeHash?.trim().toLowerCase()
 	const delivered = toNodeHash && isMailboxRecordWithinSizeLimit(record)
 		? await requireTrustGraphProvider(DEFAULT_TRUST_GRAPH_OWNER).sendToNode(username, toNodeHash, 'mailbox_put', { nodeHash, record })
 		: false
@@ -108,17 +108,17 @@ export async function publishMailboxRecord(username, toPubKeyHash, record, toNod
 }
 
 /**
- * @param {{ replicaUsername?: string }} ctx 入站上下文
+ * @param {{ replicaUsername?: string }} wireContext 入站上下文
  * @param {object} put 入站 mailbox_put
  * @param {string} [peerId] Trystero 对端 id（有则校验 nodeHash 绑定）
  * @returns {Promise<void>}
  */
-export async function ingestMailboxPut(ctx, put, peerId = '') {
+export async function ingestMailboxPut(wireContext, put, peerId = '') {
 	const { record } = put
 	if (!record?.envelope || !record?.toPubKeyHash) return
 	const fromNode = normalizeHex64(put.nodeHash)
 	if (!fromNode || !takeIncomingMailboxPutSlot(fromNode)) return
-	const username = String(ctx?.replicaUsername || '').trim()
+	const username = String(wireContext.replicaUsername || '').trim()
 	if (!username) return
 	if (peerId) {
 		const remote = await resolveRemoteNodeHashForPeer(username, peerId)
@@ -157,14 +157,14 @@ export async function respondMailboxWant(want, sendGive, peerId) {
 }
 
 /**
- * @param {{ replicaUsername?: string }} ctx 入站上下文
+ * @param {{ replicaUsername?: string }} wireContext 入站上下文
  * @param {object} give mailbox_give 载荷
  * @returns {Promise<number>} 投递给消费者的记录数
  */
-export async function ingestMailboxGive(ctx, give) {
+export async function ingestMailboxGive(wireContext, give) {
 	const records = (give.records || []).filter(isDeliverableMailboxRecord)
 	if (!records.length) return 0
-	const username = String(ctx?.replicaUsername || '').trim()
+	const username = String(wireContext.replicaUsername || '').trim()
 	if (!username) return 0
 	const { dispatchMailboxRecordsToConsumers } = await import('./consumer_registry.mjs')
 	const { deleteMailboxRecords } = await import('./store.mjs')

package/mailbox/wire.mjs

@@ -10,15 +10,15 @@ import { parseMailboxGive, parseMailboxPut, parseMailboxWant } from './parse.mjs
  */
 
 /**
- * @param {MailboxWireContext} ctx 入站上下文
+ * @param {MailboxWireContext} wireContext 入站上下文
  * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire Trystero 适配器
  * @returns {void}
  */
-export function attachMailboxWire(ctx, wire) {
+export function attachMailboxWire(wireContext, wire) {
 	wire.on('mailbox_put', (payload, peerId) => {
 		const put = parseMailboxPut(payload)
 		if (!put.ok) return
-		void ingestMailboxPut(ctx, put.value, peerId).catch(err => console.error('mailbox: put ingest failed', err))
+		void ingestMailboxPut(wireContext, put.value, peerId).catch(err => console.error('mailbox: put ingest failed', err))
 	})
 
 	wire.on('mailbox_want', (payload, peerId) => {
@@ -35,6 +35,6 @@ export function attachMailboxWire(ctx, wire) {
 	wire.on('mailbox_give', payload => {
 		const give = parseMailboxGive(payload)
 		if (!give.ok) return
-		void ingestMailboxGive(ctx, give.value).catch(err => console.error('mailbox: give ingest failed', err))
+		void ingestMailboxGive(wireContext, give.value).catch(err => console.error('mailbox: give ingest failed', err))
 	})
 }

package/node/reputation_store.mjs

@@ -26,12 +26,12 @@ import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
 
 const DATA_NAME = 'reputation'
 
-/** @type {((opts: object) => Promise<boolean>) | null} */
+/** @type {((options: object) => Promise<boolean>) | null} */
 let blockReputationHandler = null
 
 /**
  * Shell Load 时注册：公开 block/unblock → 信誉传导。
- * @param {(opts: object) => Promise<boolean>} handler block/unblock 信誉传导回调
+ * @param {(options: object) => Promise<boolean>} handler block/unblock 信誉传导回调
  * @returns {void}
  */
 export function registerBlockReputationHandler(handler) {
@@ -308,10 +308,10 @@ export function pickNodeScore(nodeId) {
 }
 
 /**
- * @param {object} opts applyFollowedBlockSignal 参数
+ * @param {object} options applyFollowedBlockSignal 参数
  * @returns {Promise<boolean>} 是否已应用
  */
-export async function applyBlockReputationSignal(opts) {
+export async function applyBlockReputationSignal(options) {
 	if (!blockReputationHandler) return false
-	return blockReputationHandler(opts)
+	return blockReputationHandler(options)
 }

package/node/retention_policy.mjs

@@ -8,16 +8,16 @@ import {
  * 在共识分支上计算须保留的事件 id（连通子图，不用拓扑下标切片）。
  * @param {string[]} order 规范拓扑序
  * @param {Map<string, object>} byId id → 事件
- * @param {object} opts 保留策略
- * @param {number} opts.maxDepth 分支上最大事件深度
- * @param {number} opts.cutoffWall 最早保留的 HLC wall
- * @param {Set<string>} opts.anchorTypes 权限锚点事件类型
- * @param {string | null} [opts.checkpointTipId] checkpoint 尖
- * @param {string | null} [opts.branchTipId] 共识分支尖
+ * @param {object} options 保留策略
+ * @param {number} options.maxDepth 分支上最大事件深度
+ * @param {number} options.cutoffWall 最早保留的 HLC wall
+ * @param {Set<string>} options.anchorTypes 权限锚点事件类型
+ * @param {string | null} [options.checkpointTipId] checkpoint 尖
+ * @param {string | null} [options.branchTipId] 共识分支尖
  * @returns {Set<string>} 保留 id
  */
-export function computeRetentionKeepIds(order, byId, opts) {
-	const { maxDepth, cutoffWall, anchorTypes, checkpointTipId, branchTipId } = opts
+export function computeRetentionKeepIds(order, byId, options) {
+	const { maxDepth, cutoffWall, anchorTypes, checkpointTipId, branchTipId } = options
 	const branchOrder = authzFoldOrderIds(order, byId, branchTipId)
 	const branchSet = new Set(branchOrder)
 	if (!branchSet.size) return new Set()

package/overlay/index.mjs

@@ -131,15 +131,15 @@ export function createOverlayRouter(registry, ttl = 3) {
 		/**
 		 * 发现到目标节点的签名路由路径。
 		 * @param {string} targetNodeHash 目标节点 64 hex
-		 * @param {object} [opts] 选项
-		 * @param {number} [opts.ttl] 路由 TTL
-		 * @param {number} [opts.timeoutMs] 超时毫秒
+		 * @param {object} [options] 选项
+		 * @param {number} [options.ttl] 路由 TTL
+		 * @param {number} [options.timeoutMs] 超时毫秒
 		 * @returns {Promise<string[]>} 从本节点到目标的 nodeHash 路径
 		 */
-		async discoverRoute(targetNodeHash, opts = {}) {
+		async discoverRoute(targetNodeHash, options = {}) {
 			const reqId = randomMsgIdHex()
-			const maxTtl = Number(opts.ttl) || ttl
-			const timeoutMs = Number(opts.timeoutMs) || 10_000
+			const maxTtl = Number(options.ttl) || ttl
+			const timeoutMs = Number(options.timeoutMs) || 10_000
 			const promise = new Promise((resolve, reject) => {
 				const timer = setTimeout(() => {
 					pendingRoutes.delete(reqId)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.5",
+	"version": "0.0.6",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

package/registries/inbound.mjs

@@ -10,11 +10,11 @@
  */
 
 /**
- * @typedef {(ctx: InboundContext, message: object) => Promise<PartInvokeResponse | null>} RpcInboundHandler
+ * @typedef {(inboundContext: InboundContext, message: object) => Promise<PartInvokeResponse | null>} RpcInboundHandler
  */
 
 /**
- * @typedef {(ctx: InboundContext, message: object) => Promise<void>} DeliveryInboundHandler
+ * @typedef {(inboundContext: InboundContext, message: object) => Promise<void>} DeliveryInboundHandler
  */
 
 /** @type {Map<string, RpcInboundHandler>} */
@@ -42,27 +42,27 @@ export function registerDeliveryInboundHandler(type, handler) {
 }
 
 /**
- * @param {InboundContext} ctx 入站上下文
+ * @param {InboundContext} inboundContext 入站上下文
  * @param {object} message 已校验的线载荷（含 type）
  * @returns {Promise<PartInvokeResponse | null>} 处理器返回值
  */
-export async function dispatchRpcInbound(ctx, message) {
+export async function dispatchRpcInbound(inboundContext, message) {
 	const type = String(message?.type || '').trim()
 	if (!type) return null
 	const handler = rpcHandlers.get(type)
 	if (!handler) return null
-	return handler(ctx, message)
+	return handler(inboundContext, message)
 }
 
 /**
- * @param {InboundContext} ctx 入站上下文
+ * @param {InboundContext} inboundContext 入站上下文
  * @param {object} message 已校验的线载荷（含 type）
  * @returns {Promise<void>}
  */
-export async function dispatchDeliveryInbound(ctx, message) {
+export async function dispatchDeliveryInbound(inboundContext, message) {
 	const type = String(message?.type || '').trim()
 	if (!type) return
 	const handler = deliveryHandlers.get(type)
 	if (!handler) return
-	await handler(ctx, message)
+	await handler(inboundContext, message)
 }

package/rooms/scoped_link.mjs

@@ -9,17 +9,17 @@ import {
 
 /**
  * 在指定 scope 与 roomSecret 下创建 link 层房间（discovery + registry 转发）。
- * @param {object} opts 房间选项
- * @param {string} opts.scope link registry scope（如 `group:{id}`）
- * @param {string} opts.roomSecret 房间 rendezvous 密钥
- * @param {(nodeHash: string) => boolean} [opts.allowNode] 是否允许与某 nodeHash 通信
- * @returns {{ start: () => Promise<void>, leave: () => Promise<void>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], onPeerJoin: (cb: (peerId: string) => void) => () => void, onPeerLeave: (cb: (peerId: string) => void) => () => void, getPeers: () => Record<string, true> }} 房间句柄
+ * @param {object} options 房间选项
+ * @param {string} options.scope link registry scope（如 `group:{id}`）
+ * @param {string} options.roomSecret 房间 rendezvous 密钥
+ * @param {(nodeHash: string) => boolean} [options.allowNode] 是否允许与某 nodeHash 通信
+ * @returns {{ start: () => Promise<void>, leave: () => Promise<void>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], onPeerJoin: (callback: (peerId: string) => void) => () => void, onPeerLeave: (callback: (peerId: string) => void) => () => void, getPeers: () => Record<string, true> }} 房间句柄
  */
-export function createScopedLinkRoom(opts) {
+export function createScopedLinkRoom(options) {
 	const registry = getLinkRegistry()
-	const scope = String(opts.scope)
-	const topic = groupRendezvousTopic(opts.roomSecret)
-	const allowNode = typeof opts.allowNode === 'function' ? opts.allowNode : () => true
+	const scope = String(options.scope)
+	const topic = groupRendezvousTopic(options.roomSecret)
+	const allowNode = typeof options.allowNode === 'function' ? options.allowNode : () => true
 	/** @type {Set<string>} */
 	const discoveredPeers = new Set()
 	/** @type {Set<string>} */
@@ -156,24 +156,24 @@ export function createScopedLinkRoom(opts) {
 			]
 		},
 		/**
-		 * @param {(peerId: string) => void} cb 新 peer 上线回调
+		 * @param {(peerId: string) => void} callback 新 peer 上线回调
 		 * @returns {() => void} 取消订阅
 		 */
-		onPeerJoin(cb) {
-			joinListeners.add(cb)
+		onPeerJoin(callback) {
+			joinListeners.add(callback)
 			for (const peerId of activePeerIds())
 				announcedPeers.add(peerId)
 			for (const peerId of announcedPeers)
-				try { cb(peerId) } catch { /* ignore */ }
-			return () => joinListeners.delete(cb)
+				try { callback(peerId) } catch { /* ignore */ }
+			return () => joinListeners.delete(callback)
 		},
 		/**
-		 * @param {(peerId: string) => void} cb peer 离线回调
+		 * @param {(peerId: string) => void} callback peer 离线回调
 		 * @returns {() => void} 取消订阅
 		 */
-		onPeerLeave(cb) {
-			leaveListeners.add(cb)
-			return () => leaveListeners.delete(cb)
+		onPeerLeave(callback) {
+			leaveListeners.add(callback)
+			return () => leaveListeners.delete(callback)
 		},
 		/**
 		 * @returns {Record<string, true>} 当前活跃 peer 的 nodeHash 集合

package/timeline/append_core.mjs

@@ -14,17 +14,17 @@ import { computeDagTipIdsFromEvents } from '../governance/branch.mjs'
  * 为追加事件计算 HLC 与 DAG 前驱（chat 群与 social 时间线共用）。
  * @param {object[]} previous 已有事件
  * @param {object} event 待追加事件
- * @param {{ multiTip?: boolean }} [opts] chat 在多 tip 时连接全部 tip
+ * @param {{ multiTip?: boolean }} [options] chat 在多 tip 时连接全部 tip
  * @returns {{ hlc: object, prev_event_ids: string[], last: object | undefined }} HLC、前驱与末条事件
  */
-export function computeAppendHlcAndPrev(previous, event, opts = {}) {
+export function computeAppendHlcAndPrev(previous, event, options = {}) {
 	const last = previous[previous.length - 1]
 	const hlc = nextHlc(last?.hlc, event.timestamp ?? Date.now())
 	const tips = computeDagTipIdsFromEvents(previous)
 	let prev_event_ids
 	if (event.prev_event_ids?.length)
 		prev_event_ids = sortedPrevEventIds(event.prev_event_ids)
-	else if (opts.multiTip && tips.length > 1)
+	else if (options.multiTip && tips.length > 1)
 		prev_event_ids = sortedPrevEventIds(tips)
 	else if (tips.length)
 		prev_event_ids = sortedPrevEventIds(tips)

package/transport/group_link_set.mjs

@@ -14,22 +14,22 @@ import { resolveFederationPoolLimits, selectLinkTargetsFromMembers } from './pee
 
 /**
  * 创建基于 link registry 的群组联邦房间。
- * @param {object} opts 选项
- * @param {string} opts.groupId 群组 id
- * @param {string} opts.roomSecret 房间密钥（用于 rendezvous topic）
- * @param {string[]} opts.members 初始成员 nodeHash 列表
- * @param {object} [opts.groupSettings] 群设置（连接预算：trustedPeerSlots/explorePeerSlots/maxPeers 等）
- * @returns {{ groupId: string, scope: string, start: () => Promise<void>, leave: () => Promise<void>, getRoster: () => Array<{ peerId: string, remoteNodeHash: string }>, getPeerIdByNodeHash: (nodeHash: string) => string | null, sendToPeer: (peerId: string, actionName: string, payload: unknown) => Promise<boolean>, send: (actionName: string, payload: unknown, peerId?: string | null) => Promise<number>, onEnvelope: (cb: (senderNodeHash: string, envelope: object) => void) => () => void, onPeerJoin: (cb: (peerId: string) => void) => () => void, onPeerLeave: (cb: (peerId: string) => void) => () => void, getPeers: () => Record<string, true>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], registerCleanup: (fn: () => void) => void, isActive: () => boolean }} 群组 link set 接口
+ * @param {object} options 选项
+ * @param {string} options.groupId 群组 id
+ * @param {string} options.roomSecret 房间密钥（用于 rendezvous topic）
+ * @param {string[]} options.members 初始成员 nodeHash 列表
+ * @param {object} [options.groupSettings] 群设置（连接预算：trustedPeerSlots/explorePeerSlots/maxPeers 等）
+ * @returns {{ groupId: string, scope: string, start: () => Promise<void>, leave: () => Promise<void>, getRoster: () => Array<{ peerId: string, remoteNodeHash: string }>, getPeerIdByNodeHash: (nodeHash: string) => string | null, sendToPeer: (peerId: string, actionName: string, payload: unknown) => Promise<boolean>, send: (actionName: string, payload: unknown, peerId?: string | null) => Promise<number>, onEnvelope: (callback: (senderNodeHash: string, envelope: object) => void) => () => void, onPeerJoin: (callback: (peerId: string) => void) => () => void, onPeerLeave: (callback: (peerId: string) => void) => () => void, getPeers: () => Record<string, true>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], registerCleanup: (cleanup: () => void) => void, isActive: () => boolean }} 群组 link set 接口
  */
-export function createGroupLinkSet(opts) {
-	const registry = opts.registry ?? getLinkRegistry()
-	const autoconnect = opts.autoconnect !== false
-	const groupId = String(opts.groupId)
+export function createGroupLinkSet(options) {
+	const registry = options.registry ?? getLinkRegistry()
+	const autoconnect = options.autoconnect !== false
+	const groupId = String(options.groupId)
 	const scope = `group:${groupId}`
-	const topic = groupRendezvousTopic(opts.roomSecret)
-	const members = new Set((Array.isArray(opts.members) ? opts.members : []).map(String))
+	const topic = groupRendezvousTopic(options.roomSecret)
+	const members = new Set((Array.isArray(options.members) ? options.members : []).map(String))
 	const selfNodeHash = registry.localIdentity.nodeHash
-	const groupSettings = opts.groupSettings ?? {}
+	const groupSettings = options.groupSettings ?? {}
 	// 初始成员是调用方明确知道的引导集合（如 introducer/creator/seed），作为必连锚点保证引导期连通。
 	const initialAnchors = new Set(members)
 	/** @type {ReturnType<typeof setTimeout> | null} */
@@ -50,12 +50,12 @@ export function createGroupLinkSet(opts) {
 
 	/**
 	 * 注册 leave 时执行的清理回调。
-	 * @param {() => void} fn 清理函数
+	 * @param {() => void} cleanup 清理函数
 	 * @returns {void}
 	 */
-	function registerCleanup(fn) {
-		if (typeof fn !== 'function') return
-		cleanups.add(fn)
+	function registerCleanup(cleanup) {
+		if (typeof cleanup !== 'function') return
+		cleanups.add(cleanup)
 	}
 
 	/**
@@ -255,34 +255,34 @@ export function createGroupLinkSet(opts) {
 		},
 		/**
 		 * 订阅入站 envelope。
-		 * @param {(senderNodeHash: string, envelope: object) => void} cb 回调
+		 * @param {(senderNodeHash: string, envelope: object) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onEnvelope(cb) {
-			envelopeListeners.add(cb)
-			return () => envelopeListeners.delete(cb)
+		onEnvelope(callback) {
+			envelopeListeners.add(callback)
+			return () => envelopeListeners.delete(callback)
 		},
 		/**
 		 * 订阅 peer 加入事件（含当前已在线 peer 的即时回调）。
-		 * @param {(peerId: string) => void} cb 回调
+		 * @param {(peerId: string) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onPeerJoin(cb) {
-			peerJoinListeners.add(cb)
+		onPeerJoin(callback) {
+			peerJoinListeners.add(callback)
 			for (const { peerId } of activeRoster())
 				if (peerId) announcedPeers.add(peerId)
 			for (const peerId of announcedPeers)
-				try { cb(peerId) } catch { /* ignore */ }
-			return () => peerJoinListeners.delete(cb)
+				try { callback(peerId) } catch { /* ignore */ }
+			return () => peerJoinListeners.delete(callback)
 		},
 		/**
 		 * 订阅 peer 离开事件。
-		 * @param {(peerId: string) => void} cb 回调
+		 * @param {(peerId: string) => void} callback 回调
 		 * @returns {() => void} 取消订阅函数
 		 */
-		onPeerLeave(cb) {
-			peerLeaveListeners.add(cb)
-			return () => peerLeaveListeners.delete(cb)
+		onPeerLeave(callback) {
+			peerLeaveListeners.add(callback)
+			return () => peerLeaveListeners.delete(callback)
 		},
 		/**
 		 * 返回当前在线 peer 的 Record 映射。

package/transport/link_registry.mjs

@@ -187,20 +187,20 @@ function subscribeBucket(buckets, key, listener) {
 
 /**
  * 创建 P2P 链路注册表（discovery、信令、直连与 overlay relay）。
- * @param {object} [opts] 选项
- * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array }} [opts.localIdentity] 本地身份
- * @param {typeof createLink} [opts.createLink] 链路工厂（可注入 mock）
- * @param {RTCConfiguration['iceServers']} [opts.iceServers] ICE 服务器列表
- * @param {number} [opts.maxActive] 最大并发活跃链路数
- * @param {boolean} [opts.autoRegisterDiscoveryProviders] 是否自动注册 discovery provider
+ * @param {object} [options] 选项
+ * @param {{ nodeHash?: string, nodePubKey?: string, secretKey?: Uint8Array }} [options.localIdentity] 本地身份
+ * @param {typeof createLink} [options.createLink] 链路工厂（可注入 mock）
+ * @param {RTCConfiguration['iceServers']} [options.iceServers] ICE 服务器列表
+ * @param {number} [options.maxActive] 最大并发活跃链路数
+ * @param {boolean} [options.autoRegisterDiscoveryProviders] 是否自动注册 discovery provider
  * @returns {object} link registry 接口
  */
-export function createLinkRegistry(opts = {}) {
-	const localIdentity = resolveLocalIdentity(opts.localIdentity)
-	const createLinkImpl = opts.createLink ?? createLink
-	const iceServers = opts.iceServers?.length ? opts.iceServers : DEFAULT_ICE_SERVERS
-	const maxActive = Math.max(4, Number(opts.maxActive) || 32)
-	const autoRegisterDiscoveryProviders = opts.autoRegisterDiscoveryProviders !== false
+export function createLinkRegistry(options = {}) {
+	const localIdentity = resolveLocalIdentity(options.localIdentity)
+	const createLinkImpl = options.createLink ?? createLink
+	const iceServers = options.iceServers?.length ? options.iceServers : DEFAULT_ICE_SERVERS
+	const maxActive = Math.max(4, Number(options.maxActive) || 32)
+	const autoRegisterDiscoveryProviders = options.autoRegisterDiscoveryProviders !== false
 	const selfTopic = nodeRendezvousTopic(localIdentity.nodeHash)
 	/** @type {Map<string, Awaited<ReturnType<typeof createLinkImpl>>>} */
 	const links = new Map()
@@ -348,7 +348,7 @@ export function createLinkRegistry(opts = {}) {
 	/**
 	 * 为一条 connId 会话建 PC 并走 glare 择一：建 link → 绑 onDown 清 session → ready → registerResolvedLink。
 	 * initiator 侧建链前先 trimToBudget 腾预算。出错则清理该 connId 会话。
-	 * @param {{ remoteNodeHash: string, connId: string, session: ReturnType<typeof createBufferedSignalSession>, initiator: boolean }} opts 建链参数
+	 * @param {{ remoteNodeHash: string, connId: string, session: ReturnType<typeof createBufferedSignalSession>, initiator: boolean }} options 建链参数
 	 * @returns {Promise<Awaited<ReturnType<typeof createLinkImpl>> | null>} 当前规范链（本条可能因 glare 被关，取 links 现值）；失败 null
 	 */
 	async function buildConnLink({ remoteNodeHash, connId, session, initiator }) {

package/transport/peer_pool.mjs

@@ -141,7 +141,7 @@ export function selectExploreWithSourceQuota(exploreIds, exploreSources, k, maxP
  *   selfNodeHash: string,
  *   inRoomNodeHashes?: Set<string> | string[] 群内在线 node_id；有则优先，仅全不可达时用 explore 中非房内节点
  *   hintSources?: Map<string, string> explore 节点来源（用于配额）
- * }} opts 选取参数（roster、peers、rep、limits、selfNodeHash）
+ * }} options 选取参数（roster、peers、rep、limits、selfNodeHash）
  * @returns {string[]} 目标 Trystero peerId 列表（去重，长度 ≤ maxPeers）
  */
 export function selectPeerIdsFromPool({ roster, peers, rep, limits, selfNodeHash, inRoomNodeHashes, hintSources }) {
@@ -212,7 +212,7 @@ export function selectPeerIdsFromPool({ roster, peers, rep, limits, selfNodeHash
  *   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）
+ * }} options 选取参数（members、selfNodeHash、rep、peers、limits、anchors）
  * @returns {string[]} 应建链的 nodeHash 列表（去重）
  */
 export function selectLinkTargetsFromMembers({ members, selfNodeHash, rep, peers, limits, anchors = [] }) {
@@ -245,7 +245,7 @@ export function selectLinkTargetsFromMembers({ members, selfNodeHash, rep, peers
  *   rep: { byNodeHash?: Record<string, { score?: number }> },
  *   hints: string[],
  *   limits: ReturnType<typeof resolveFederationPoolLimits>,
- * }} opts 合并参数（peers、rep、hints、limits）
+ * }} options 合并参数（peers、rep、hints、limits）
  * @returns {{ trustedPeers: string[], explorePeers: string[] }} 更新后的 trusted/explore 列表
  */
 export function applyPexHints({ peers, rep, hints, limits }) {
@@ -275,7 +275,7 @@ export function applyPexHints({ peers, rep, hints, limits }) {
  *   rep: { byNodeHash?: Record<string, { score?: number }> },
  *   roster: Array<{ remoteNodeHash?: string }>,
  *   limits: ReturnType<typeof resolveFederationPoolLimits>,
- * }} opts roster 更新参数（peers、rep、roster、limits）
+ * }} options roster 更新参数（peers、rep、roster、limits）
  * @returns {{ trustedPeers: string[], explorePeers: string[] }} 更新后的 trusted/explore 列表
  */
 export function applyRosterToPeerPool({ peers, rep, roster, limits }) {