@steve02081504/fount-p2p 0.0.5 → 0.0.7

package/core/tcp_port.mjs

@@ -0,0 +1,11 @@
+/**
+ * 规范化 TCP 端口（advert / peer hint 共用）。
+ * @param {unknown} port 原始端口
+ * @returns {number | null} 有效端口或 null（未提供 / 非法）
+ */
+export function normalizeTcpPort(port) {
+	if (port == null || port === '') return null
+	const value = Number(port)
+	if (!Number.isInteger(value) || value < 1 || value > 65535) return null
+	return value
+}

package/dag/canonicalize_row.mjs

@@ -47,19 +47,19 @@ export function canonicalizeRowContent(content, hexKeys, entityHashKeys = new Se
  *   prepare?: (event: object) => object,
  *   contentHexKeys?: ReadonlySet<string>,
  *   entityHashKeys?: ReadonlySet<string>,
- * }} [opts] 各域字段集
+ * }} [options] 各域字段集
  * @returns {object} canonical 行
  */
-export function canonicalizeSignedRow(event, opts = {}) {
-	const out = opts.prepare ? opts.prepare({ ...event }) : { ...event }
+export function canonicalizeSignedRow(event, options = {}) {
+	const out = options.prepare ? options.prepare({ ...event }) : { ...event }
 	out.id = assertHex64(out.id, 'id')
 	out.sender = assertHex64(out.sender, 'sender')
 	if (Array.isArray(out.prev_event_ids))
 		out.prev_event_ids = out.prev_event_ids.map((id, index) =>
 			assertHex64(id, `prev_event_ids[${index}]`),
 		)
-	const hexKeys = opts.contentHexKeys
+	const hexKeys = options.contentHexKeys
 	if (out.content && hexKeys?.size)
-		out.content = canonicalizeRowContent(out.content, hexKeys, opts.entityHashKeys)
+		out.content = canonicalizeRowContent(out.content, hexKeys, options.entityHashKeys)
 	return out
 }

package/discovery/advert_peer_hints.mjs

@@ -0,0 +1,21 @@
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+
+import { noteBtPeerHint } from './bt/peer_hints.mjs'
+import { noteLanPeerHint } from './lan_peer_hints.mjs'
+
+/**
+ * 从已验证的 discovery advert + provider meta 写入 LAN/BT peer hints。
+ * 任意 discovery 路径（node / group / scoped topic）收到 advert 时都应调用。
+ * @param {string} verifiedNodeHash 验签通过的 nodeHash
+ * @param {{ tcpPort?: unknown } | null | undefined} body advert body
+ * @param {{ address?: unknown, peripheralId?: unknown } | null | undefined} meta discovery provider meta
+ * @returns {void}
+ */
+export function noteAdvertPeerHints(verifiedNodeHash, body, meta) {
+	if (meta?.peripheralId)
+		noteBtPeerHint(verifiedNodeHash, meta.peripheralId)
+	const tcpPort = normalizeTcpPort(body?.tcpPort)
+	const address = String(meta?.address || '').trim()
+	if (tcpPort != null && address)
+		noteLanPeerHint(verifiedNodeHash, { host: address, port: tcpPort })
+}

package/discovery/{bt.mjs → bt/index.mjs}

@@ -1,56 +1,19 @@
 import { Buffer } from 'node:buffer'
-import process from 'node:process'
+
+import { getBtPeerHint } from './peer_hints.mjs'
+import { loadBleno, loadNoble, resolveBtRole, waitPoweredOn } from './runtime.mjs'
+
+/** 重导出 waitPoweredOn，供 discovery 调用方使用。 */
+export { waitPoweredOn } from './runtime.mjs'
 
 const BT_SERVICE_UUID = 'f017f017f017f017f017f017f017f017'
 const BT_CHARACTERISTIC_UUID = 'f017f017f017f017f017f017f017f018'
+const BT_SIGNAL_CHAR_UUID = 'f017f017f017f017f017f017f017f01b'
 const BT_DEVICE_NAME = 'fount-bt'
 const MAX_ADVERT_BLOB_BYTES = 12 * 1024
+const MAX_SIGNAL_BLOB_BYTES = 8 * 1024
 const PERIPHERAL_RESCAN_MS = 15_000
 
-/**
- * 解析 Bluetooth 发现角色（scan / dual）。
- * @returns {'scan' | 'dual'} 当前平台或环境变量指定的角色
- */
-function resolveBtRole() {
-	const override = String(process.env.FOUNT_BT_DISCOVERY_ROLE || '').trim().toLowerCase()
-	if (override === 'dual') return 'dual'
-	if (override === 'scan') return 'scan'
-	return process.platform === 'win32' ? 'scan' : 'dual'
-}
-
-/**
- * 加载 Noble BLE central 库。
- * @returns {Promise<any>} Noble 运行时实例
- */
-async function loadNoble() {
-	const mod = await import('@stoprocent/noble')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
-}
-
-/**
- * 加载 Bleno BLE peripheral 库。
- * @returns {Promise<any>} Bleno 运行时实例
- */
-async function loadBleno() {
-	const mod = await import('@stoprocent/bleno')
-	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
-	return mod.default ?? mod
-}
-
-/**
- * 等待 BLE 运行时进入 poweredOn（兼容 noble v1/v2 与 bleno）。
- * @param {*} runtime noble 或 bleno 实例
- * @param {number} [timeout] 超时毫秒
- * @returns {Promise<void>}
- */
-export async function waitPoweredOn(runtime, timeout) {
-	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
-	if (typeof wait !== 'function')
-		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
-	return wait.call(runtime, timeout)
-}
-
 /**
  * 探测本机 noble 运行时是否具备 BT 扫描所需 API。
  * @returns {Promise<boolean>} noble 可加载且具备 startScanningAsync 与 waitForPoweredOn(Async) 时为 true
@@ -125,6 +88,7 @@ function addListener(bucket, topic, listener) {
  * - 默认在 Windows 上只启用 scan 侧发现（单适配器 central+peripheral 常冲突）
  * - 其他平台默认 dual：advertise + scan
  * - 通过固定 BLE service + read characteristic 传输完整 advert 列表，避免 31-byte 广告包限制
+ * - dual 下额外暴露 write characteristic 传短信令；central 可按 peer hint 写信令
  *
  * @returns {import('./index.mjs').DiscoveryProvider} Bluetooth 发现提供者
  */
@@ -134,6 +98,8 @@ export function createBluetoothDiscoveryProvider() {
 	const adverts = new Map()
 	/** @type {Map<string, Set<Function>>} */
 	const advertListeners = new Map()
+	/** @type {Map<string, Set<Function>>} */
+	const signalListeners = new Map()
 	/** @type {Map<string, number>} */
 	const inspectedAt = new Map()
 	let nobleRuntime = null
@@ -149,17 +115,17 @@ export function createBluetoothDiscoveryProvider() {
 		if (role === 'scan') return null
 		if (blenoRuntime) return blenoRuntime
 		const bleno = await loadBleno()
-		const characteristic = new bleno.Characteristic({
+		const advertCharacteristic = new bleno.Characteristic({
 			uuid: BT_CHARACTERISTIC_UUID,
 			properties: ['read'],
 			/**
-			 * BLE characteristic 读请求回调。
-			 * @param {*} _handle Bleno handle（未使用）
-			 * @param {number} offset 读取偏移
-			 * @param {Function} callback Bleno 结果回调
+			 * stoprocent/bleno onReadRequest(connection, offset, callback)
+			 * @param {*} _connection 连接句柄
+			 * @param {number} offset 偏移
+			 * @param {Function} callback 结果
 			 * @returns {void}
 			 */
-			onReadRequest(_handle, offset, callback) {
+			onReadRequest(_connection, offset, callback) {
 				try {
 					const blob = serializeAdvertBlob(adverts)
 					if (offset > blob.length) {
@@ -173,11 +139,39 @@ export function createBluetoothDiscoveryProvider() {
 				}
 			},
 		})
+		const signalCharacteristic = new bleno.Characteristic({
+			uuid: BT_SIGNAL_CHAR_UUID,
+			properties: ['write', 'writeWithoutResponse'],
+			/**
+			 * stoprocent/bleno onWriteRequest(connection, data, offset, withoutResponse, callback)
+			 * @param {*} _connection 连接句柄
+			 * @param {Buffer} data 信令 blob
+			 * @param {number} _offset 偏移
+			 * @param {boolean} _withoutResponse 无响应写
+			 * @param {Function} callback 结果
+			 * @returns {void}
+			 */
+			onWriteRequest(_connection, data, _offset, _withoutResponse, callback) {
+				try {
+					const parsed = JSON.parse(Buffer.from(data).toString('utf8'))
+					const topic = String(parsed?.topic || '')
+					const bytes = Uint8Array.from(Buffer.from(String(parsed?.data || ''), 'base64'))
+					if (topic && bytes.byteLength) 
+						for (const listener of signalListeners.get(topic) || [])
+							listener(bytes, { provider: 'bt' })
+					
+					callback(bleno.Characteristic.RESULT_SUCCESS)
+				}
+				catch {
+					callback(bleno.Characteristic.RESULT_UNLIKELY_ERROR)
+				}
+			},
+		})
 		await waitPoweredOn(bleno, 5_000)
 		await bleno.setServicesAsync([
 			new bleno.PrimaryService({
 				uuid: BT_SERVICE_UUID,
-				characteristics: [characteristic],
+				characteristics: [advertCharacteristic, signalCharacteristic],
 			}),
 		])
 		blenoRuntime = bleno
@@ -192,14 +186,14 @@ export function createBluetoothDiscoveryProvider() {
 		if (role === 'scan') return
 		const bleno = await ensurePeripheralRuntime()
 		if (!bleno) return
-		if (!adverts.size) {
+		if (!adverts.size && !signalListeners.size) {
 			if (advertisingStarted) {
 				await bleno.stopAdvertisingAsync().catch(() => { })
 				advertisingStarted = false
 			}
 			return
 		}
-		serializeAdvertBlob(adverts)
+		if (adverts.size) serializeAdvertBlob(adverts)
 		if (!advertisingStarted) {
 			await bleno.startAdvertisingAsync(BT_DEVICE_NAME, [BT_SERVICE_UUID])
 			advertisingStarted = true
@@ -256,10 +250,86 @@ export function createBluetoothDiscoveryProvider() {
 		scanningStarted = true
 	}
 
+	/**
+	 * Central：按 peer hint 连接并对端 signal characteristic 写短包。
+	 * @param {string} topic 信令 topic
+	 * @param {string} to 目标 nodeHash
+	 * @param {Uint8Array} bytes 载荷
+	 * @returns {Promise<void>}
+	 */
+	async function sendSignalViaGatt(topic, to, bytes) {
+		const hint = getBtPeerHint(to)
+		if (!hint) throw new Error('p2p: bt signal missing peer hint')
+		const blob = Buffer.from(JSON.stringify({
+			topic: String(topic),
+			to: String(to),
+			data: Buffer.from(bytes).toString('base64'),
+		}), 'utf8')
+		if (blob.byteLength > MAX_SIGNAL_BLOB_BYTES)
+			throw new Error(`p2p: bt signal blob exceeds ${MAX_SIGNAL_BLOB_BYTES} bytes`)
+		await ensureScanRuntime()
+		const noble = nobleRuntime
+		const wantId = hint.peripheralId
+		/**
+		 * 先查 noble 已缓存的 peripheral，避免只等下一次 advertise 漏报。
+		 * @returns {*|null} 已缓存的 peripheral，未命中为 null
+		 */
+		function cachedPeripheral() {
+			const table = noble?._peripherals
+			if (!table || typeof table !== 'object') return null
+			for (const found of Object.values(table)) {
+				const id = String(found?.id || found?.address || '')
+				if (id === wantId) return found
+			}
+			return null
+		}
+		const peripheral = cachedPeripheral() ?? await new Promise((resolve, reject) => {
+			const deadline = setTimeout(() => {
+				cleanup()
+				reject(new Error('p2p: bt signal peripheral timeout'))
+			}, 8_000)
+			/**
+			 * @returns {void}
+			 */
+			function cleanup() {
+				clearTimeout(deadline)
+				noble.removeListener('discover', onDiscover)
+			}
+			/**
+			 * @param {*} found peripheral
+			 * @returns {void}
+			 */
+			function onDiscover(found) {
+				const id = String(found?.id || found?.address || '')
+				if (id !== wantId) return
+				cleanup()
+				resolve(found)
+			}
+			noble.on('discover', onDiscover)
+			const again = cachedPeripheral()
+			if (again) {
+				cleanup()
+				resolve(again)
+			}
+		})
+		try {
+			await peripheral.connectAsync()
+			const { characteristics } = await peripheral.discoverSomeServicesAndCharacteristicsAsync(
+				[BT_SERVICE_UUID],
+				[BT_SIGNAL_CHAR_UUID],
+			)
+			if (!characteristics?.length) throw new Error('p2p: bt signal characteristic missing')
+			await characteristics[0].writeAsync(blob, false)
+		}
+		finally {
+			try { await peripheral.disconnectAsync() } catch { /* ignore */ }
+		}
+	}
+
 	return {
 		id: 'bt',
 		priority: 20,
-		caps: { canDiscover: true, canSignal: false, canRelay: false },
+		caps: { canDiscover: true, canSignal: true, canRelay: false },
 		/**
 		 * 广播指定 topic 的 advert。
 		 * @param {string} topic advert 主题
@@ -285,5 +355,31 @@ export function createBluetoothDiscoveryProvider() {
 			await ensureScanRuntime()
 			return addListener(advertListeners, String(topic), onAdvert)
 		},
+		/**
+		 * 经 GATT 向近场 peer 发送信令。
+		 * @param {string} topic 信令 topic
+		 * @param {string} to 目标 nodeHash
+		 * @param {Uint8Array} bytes 载荷
+		 * @returns {Promise<void>}
+		 */
+		async sendSignal(topic, to, bytes) {
+			await sendSignalViaGatt(topic, to, bytes)
+		},
+		/**
+		 * 监听经本机 peripheral signal characteristic 写入的信令。
+		 * @param {string} topic 信令 topic
+		 * @param {Function} onSignal 回调
+		 * @returns {Promise<() => void>} 取消订阅
+		 */
+		async onSignal(topic, onSignal) {
+			if (role === 'scan') return () => { }
+			await ensurePeripheralRuntime()
+			await refreshAdvertising()
+			const stop = addListener(signalListeners, String(topic), onSignal)
+			return () => {
+				stop()
+				void refreshAdvertising().catch(() => { })
+			}
+		},
 	}
 }

package/discovery/bt/peer_hints.mjs

@@ -0,0 +1,41 @@
+import { normalizeHex64 } from '../../core/hexIds.mjs'
+import { createTtlMap } from '../../utils/ttl_map.mjs'
+
+/** BT peer hint 存活时间。 */
+export const BT_PEER_HINT_TTL_MS = 5 * 60_000
+
+/** @type {ReturnType<typeof createTtlMap<{ peripheralId: string }>>} */
+const hints = createTtlMap(BT_PEER_HINT_TTL_MS)
+
+/**
+ * 记录近场 BT 扫描到的 nodeHash → peripheral 映射。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {string} peripheralId noble peripheral id / address
+ * @returns {void}
+ */
+export function noteBtPeerHint(nodeHash, peripheralId) {
+	const hash = normalizeHex64(nodeHash)
+	const id = String(peripheralId || '').trim()
+	if (!hash || !id) return
+	hints.set(hash, { peripheralId: id })
+}
+
+/**
+ * 查询未过期的 BT peer hint。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {number} [now=Date.now()] 当前时间（测试可注入）
+ * @returns {{ peripheralId: string } | null} hint 或 null
+ */
+export function getBtPeerHint(nodeHash, now = Date.now()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!hash) return null
+	return hints.get(hash, now)
+}
+
+/**
+ * 清空全部 BT peer hints（测试用）。
+ * @returns {void}
+ */
+export function clearBtPeerHints() {
+	hints.clear()
+}

package/discovery/bt/runtime.mjs

@@ -0,0 +1,46 @@
+import process from 'node:process'
+
+/**
+ * 解析 Bluetooth 角色（scan / dual）。
+ * Win32 默认 scan（单适配器 central+peripheral 常冲突）；可用 FOUNT_BT_DISCOVERY_ROLE 覆盖。
+ * @returns {'scan' | 'dual'} 生效角色
+ */
+export function resolveBtRole() {
+	const override = String(process.env.FOUNT_BT_DISCOVERY_ROLE || '').trim().toLowerCase()
+	if (override === 'dual') return 'dual'
+	if (override === 'scan') return 'scan'
+	return process.platform === 'win32' ? 'scan' : 'dual'
+}
+
+/**
+ * 加载 Noble BLE central。
+ * @returns {Promise<any>} noble 运行时
+ */
+export async function loadNoble() {
+	const mod = await import('@stoprocent/noble')
+	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
+	return mod.default ?? mod
+}
+
+/**
+ * 加载 Bleno BLE peripheral。
+ * @returns {Promise<any>} bleno 运行时
+ */
+export async function loadBleno() {
+	const mod = await import('@stoprocent/bleno')
+	if (typeof mod.withBindings === 'function') return mod.withBindings('default')
+	return mod.default ?? mod
+}
+
+/**
+ * 等待 BLE 运行时 poweredOn（兼容 noble/bleno v1/v2）。
+ * @param {*} runtime noble 或 bleno
+ * @param {number} [timeout] 超时毫秒
+ * @returns {Promise<void>}
+ */
+export async function waitPoweredOn(runtime, timeout) {
+	const wait = runtime.waitForPoweredOnAsync ?? runtime.waitForPoweredOn
+	if (typeof wait !== 'function')
+		throw new Error('p2p: bluetooth runtime missing waitForPoweredOn(Async)')
+	return wait.call(runtime, timeout)
+}

package/discovery/lan_peer_hints.mjs

@@ -0,0 +1,43 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { normalizeTcpPort } from '../core/tcp_port.mjs'
+import { createTtlMap } from '../utils/ttl_map.mjs'
+
+/** LAN peer hint 存活时间。 */
+export const LAN_PEER_HINT_TTL_MS = 5 * 60_000
+
+/** @type {ReturnType<typeof createTtlMap<{ host: string, port: number }>>} */
+const hints = createTtlMap(LAN_PEER_HINT_TTL_MS)
+
+/**
+ * 记录 LAN 上观察到的 nodeHash → host:port。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {{ host: string, port: number }} endpoint 端点
+ * @returns {void}
+ */
+export function noteLanPeerHint(nodeHash, endpoint) {
+	const hash = normalizeHex64(nodeHash)
+	const host = String(endpoint?.host || '').trim()
+	const port = normalizeTcpPort(endpoint?.port)
+	if (!hash || !host || !port) return
+	hints.set(hash, { host, port })
+}
+
+/**
+ * 查询未过期的 LAN peer hint。
+ * @param {string} nodeHash 节点 64 hex
+ * @param {number} [now=Date.now()] 当前时间（测试可注入）
+ * @returns {{ host: string, port: number } | null} hint 或 null
+ */
+export function getLanPeerHint(nodeHash, now = Date.now()) {
+	const hash = normalizeHex64(nodeHash)
+	if (!hash) return null
+	return hints.get(hash, now)
+}
+
+/**
+ * 清空全部 LAN peer hints（测试用）。
+ * @returns {void}
+ */
+export function clearLanPeerHints() {
+	hints.clear()
+}

package/discovery/mdns.mjs

@@ -7,12 +7,12 @@ const DEFAULT_GROUP = '239.255.42.99'
 /**
  * 轻量 multicast 发现插件：不做完整 DNS-SD，只复用 mDNS 的 LAN multicast 发现思路。
  *
- * @param {{ port?: number, group?: string }} [opts] 组播端口与组地址
+ * @param {{ port?: number, group?: string }} [options] 组播端口与组地址
  * @returns {import('./index.mjs').DiscoveryProvider} mDNS 发现提供者
  */
-export function createMdnsDiscoveryProvider(opts = {}) {
-	const port = Number(opts.port) || DEFAULT_PORT
-	const group = String(opts.group || DEFAULT_GROUP)
+export function createMdnsDiscoveryProvider(options = {}) {
+	const port = Number(options.port) || DEFAULT_PORT
+	const group = String(options.group || DEFAULT_GROUP)
 	const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true })
 	let bound = false
 	let bindPromise = null
@@ -38,7 +38,7 @@ export function createMdnsDiscoveryProvider(opts = {}) {
 						resolve()
 					})
 				})
-				socket.on('message', raw => {
+				socket.on('message', (raw, rinfo) => {
 					let packet
 					try { packet = JSON.parse(String(raw)) } catch { return }
 					const listeners = packet.type === 'advert'
@@ -46,8 +46,12 @@ export function createMdnsDiscoveryProvider(opts = {}) {
 						: signalListeners.get(String(packet.topic || ''))
 					if (!listeners?.size) return
 					const bytes = Uint8Array.from(Buffer.from(String(packet.data || ''), 'base64'))
+					const meta = {
+						provider: 'mdns',
+						address: String(rinfo?.address || ''),
+					}
 					for (const listener of listeners)
-						listener(bytes, { provider: 'mdns' })
+						listener(bytes, meta)
 				})
 				bound = true
 			})()

package/discovery/nostr.mjs

@@ -142,11 +142,11 @@ async function publishEvent(relayUrls, event) {
 
 /**
  * 创建 Nostr discovery provider。
- * @param {{ relayUrls?: string[] }} [opts] 可选中继 URL 覆盖
+ * @param {{ relayUrls?: string[] }} [options] 可选中继 URL 覆盖
  * @returns {import('./index.mjs').DiscoveryProvider} Nostr 发现提供者
  */
-export function createNostrDiscoveryProvider(opts = {}) {
-	const relayUrls = mergeSignalingRelayUrls(opts.relayUrls)
+export function createNostrDiscoveryProvider(options = {}) {
+	const relayUrls = mergeSignalingRelayUrls(options.relayUrls)
 	const secretKey = randomBytes(32)
 	return {
 		id: 'nostr',

package/federation/chunk_fetch_pending.mjs

@@ -14,10 +14,10 @@ export const MAX_PENDING_CHUNK_FETCHES = 2048
  * @param {string} key 唯一等待键
  * @param {string} expectedHash 期望 64 hex 密文哈希
  * @param {number} timeoutMs 超时毫秒
- * @param {{ rejectOnTimeout?: boolean }} [opts] rejectOnTimeout 时 Promise 以 Error 拒绝
+ * @param {{ rejectOnTimeout?: boolean }} [options] rejectOnTimeout 时 Promise 以 Error 拒绝
  * @returns {{ done: Promise<Uint8Array | null>, cancel: () => void }} 等待 Promise 与取消函数
  */
-export function registerChunkFetchWait(key, expectedHash, timeoutMs, opts = {}) {
+export function registerChunkFetchWait(key, expectedHash, timeoutMs, options = {}) {
 	if (!key || pendingChunkFetches.size >= MAX_PENDING_CHUNK_FETCHES)
 		return {
 			done: Promise.resolve(null), /**
@@ -41,7 +41,7 @@ export function registerChunkFetchWait(key, expectedHash, timeoutMs, opts = {})
 	})
 	const timer = setTimeout(() => {
 		pendingChunkFetches.delete(key)
-		if (opts.rejectOnTimeout)
+		if (options.rejectOnTimeout)
 			settle(new Error('chunk fetch timeout'))
 		else
 			settle(null)

package/federation/chunk_fetch_scheduler.mjs

@@ -23,11 +23,11 @@ export function assignChunksToPeers(chunkHashes, peerIds) {
  * @param {Map<string, { state: ChunkFetchState, peerId?: string, attempts: number }>} table 状态表
  * @param {string[]} chunkHashes 待拉取块
  * @param {string[]} peerIds 可用 peer
- * @param {{ maxAttempts?: number }} [opts] 选项
+ * @param {{ maxAttempts?: number }} [options] 选项
  * @returns {{ assignments: Map<string, string>, broadcast: string[] }} 分配与需广播块
  */
-export function planChunkFetches(table, chunkHashes, peerIds, opts = {}) {
-	const maxAttempts = Math.max(1, Number(opts.maxAttempts) || 3)
+export function planChunkFetches(table, chunkHashes, peerIds, options = {}) {
+	const maxAttempts = Math.max(1, Number(options.maxAttempts) || 3)
 	const assignments = assignChunksToPeers(chunkHashes, peerIds)
 	/** @type {string[]} */
 	const broadcast = []

package/federation/dag_order_cache.mjs

@@ -43,12 +43,12 @@ export function mergeTopologicalOrder(cachedOrder, events) {
 /**
  * @param {object[]} events 全量事件
  * @param {object | null} cache 磁盘缓存
- * @param {{ forceFull?: boolean }} [opts] 选项
+ * @param {{ forceFull?: boolean }} [options] 选项
  * @returns {string[]} 拓扑序 id 列表
  */
-export function resolveEventTopologicalOrder(events, cache, opts = {}) {
+export function resolveEventTopologicalOrder(events, cache, options = {}) {
 	if (!events.length) return []
-	if (opts.forceFull)
+	if (options.forceFull)
 		return topologicalCanonicalOrder(eventsToMetas(events))
 
 	const byId = new Map(events.map(event => [event.id, event]))

package/federation/topo_order_memo.mjs

@@ -6,11 +6,11 @@ const memoByKey = new Map()
  * @param {string} memoKey 缓存键
  * @param {string} fingerprint 文件 stat + 事件数指纹
  * @param {() => string[]} resolveOrder 实际求序（含磁盘层）
- * @param {{ force?: boolean }} [opts] 强制重算
+ * @param {{ force?: boolean }} [options] 强制重算
  * @returns {string[]} 拓扑序 event id
  */
-export function resolveTopologicalOrderMemoCached(memoKey, fingerprint, resolveOrder, opts = {}) {
-	if (!opts.force) {
+export function resolveTopologicalOrderMemoCached(memoKey, fingerprint, resolveOrder, options = {}) {
+	if (!options.force) {
 		const cached = memoByKey.get(memoKey)
 		if (cached?.fp === fingerprint && cached.order.length)
 			return cached.order

package/files/chunk_responder.mjs

@@ -71,7 +71,7 @@ export function attachNodeScopeFedChunkResponder(username, wire) {
  * Trystero room：注册带 requestId 的 fed_chunk_* + fed_manifest_*（TrustGraph 全局 miss）。
  * @param {string} username 用户
  * @param {object} room Trystero room
- * @param {{ enqueue: (prio: number, fn: () => void) => void }} [fedOut] 出站队列
+ * @param {{ enqueue: (prio: number, cleanup: () => void) => void }} [fedOut] 出站队列
  * @param {(roomKey: string, action: string, rtcLimits: object) => boolean} [guardGet] RTC 负载守卫
  * @param {object} [rtcLimits] RTC 限额
  * @param {string} [roomKey] 房间键