@steve02081504/fount-p2p 0.0.11 → 0.0.13

package/link/frame.mjs

@@ -1,90 +1,56 @@
 import { randomBytes } from 'node:crypto'
 
-/**
- * 二进制帧协议版本号。
- */
-export const FRAME_VERSION = 1
-/**
- * msgId 字段字节长度（128 位）。
- */
-export const FRAME_MSG_ID_BYTES = 16
-/**
- * 帧头字节长度：version(1) + msgId(16) + seq(4) + total(4)。
- */
-export const FRAME_HEADER_BYTES = 1 + FRAME_MSG_ID_BYTES + 4 + 4
-/**
- * 默认单帧最大 chunk 大小（15 KiB）。
- */
+import { bytesToHex, hexToBytes, toBytes } from '../core/bytes_codec.mjs'
+
+/** frameId 字段字节长度（128 位）。 */
+export const FRAME_ID_BYTES = 16
+/** 帧头：frameId(16) + seq(4) + total(4)。 */
+export const FRAME_HEADER_BYTES = FRAME_ID_BYTES + 4 + 4
+/** 默认单帧最大 chunk 大小（15 KiB）。 */
 export const DEFAULT_MAX_FRAME_CHUNK_BYTES = 15 * 1024
-/**
- * 重组后消息最大字节数（8 MiB）。
- */
+/** 重组后消息最大字节数（8 MiB）。 */
 export const DEFAULT_MAX_MESSAGE_BYTES = 8 * 1024 * 1024
-/**
- * 同时进行中的分片消息数量上限。
- */
+/** 同时进行中的分片消息数量上限。 */
 export const DEFAULT_MAX_PARTIAL_MESSAGES = 32
-/**
- * 分片消息超时时间（毫秒）。
- */
+/** 分片消息超时时间（毫秒）。 */
 export const DEFAULT_PARTIAL_TIMEOUT_MS = 30_000
 
 /**
- * 将输入规范化为 Uint8Array。
- * @param {unknown} value 原始字节数据
- * @returns {Uint8Array} 字节视图
+ * @param {string | Uint8Array} frameId hex 或 16 字节
+ * @returns {Uint8Array} 规范化后的 16 字节 frameId
  */
-function normalizeBytes(value) {
-	if (value instanceof Uint8Array) return value
-	if (value instanceof ArrayBuffer) return new Uint8Array(value)
-	if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
-	throw new Error('p2p: frame bytes must be Uint8Array-compatible')
-}
-
-/**
- * 将 msgId 规范化为 16 字节 Uint8Array。
- * @param {unknown} msgId hex 字符串或 16 字节 Uint8Array
- * @returns {Uint8Array} 16 字节 msgId
- */
-function normalizeMsgIdBytes(msgId) {
-	if (msgId instanceof Uint8Array) {
-		if (msgId.byteLength !== FRAME_MSG_ID_BYTES)
-			throw new Error(`p2p: msgId must be ${FRAME_MSG_ID_BYTES} bytes`)
-		return msgId
+function normalizeFrameIdBytes(frameId) {
+	if (frameId instanceof Uint8Array) {
+		if (frameId.byteLength !== FRAME_ID_BYTES)
+			throw new Error(`p2p: frameId must be ${FRAME_ID_BYTES} bytes`)
+		return frameId
+	}
+	const text = frameId.trim().toLowerCase()
+	if (text.length !== FRAME_ID_BYTES * 2)
+		throw new Error('p2p: frameId must be 32 hex characters')
+	try {
+		return hexToBytes(text)
+	}
+	catch {
+		throw new Error('p2p: frameId must be 32 hex characters')
 	}
-	const text = String(msgId ?? '').trim().toLowerCase()
-	if (!/^[\da-f]{32}$/u.test(text))
-		throw new Error('p2p: msgId must be 32 hex characters')
-	return Uint8Array.from(text.match(/../g).map(chunk => Number.parseInt(chunk, 16)))
-}
-
-/**
- * 将 msgId 字节转为 32 字符小写 hex。
- * @param {Uint8Array} bytes 16 字节 msgId
- * @returns {string} hex 字符串
- */
-export function msgIdBytesToHex(bytes) {
-	return [...bytes].map(byte => byte.toString(16).padStart(2, '0')).join('')
 }
 
-/**
- * 生成随机 msgId hex 字符串。
- * @returns {string} 32 字符 hex msgId
- */
-export function randomMsgIdHex() {
-	return msgIdBytesToHex(randomBytes(FRAME_MSG_ID_BYTES))
+/** @returns {string} 32 字符 hex frameId */
+export function randomFrameIdHex() {
+	return bytesToHex(randomBytes(FRAME_ID_BYTES))
 }
 
 /**
- * 将消息体拆分为带帧头的二进制帧数组。
- * @param {string | Uint8Array} msgId 消息 ID
- * @param {Uint8Array | ArrayBuffer | ArrayBufferView} bytes 消息体字节
- * @param {number} [maxChunkBytes=DEFAULT_MAX_FRAME_CHUNK_BYTES] 单帧最大 chunk 大小
- * @returns {Uint8Array[]} 帧数组
+ * 将消息切成带帧头的分片。
+ * @param {string | Uint8Array} frameId 消息 id（hex 或 16 字节）
+ * @param {Uint8Array | ArrayBuffer | ArrayBufferView} bytes 消息体
+ * @param {number} [maxChunkBytes] 单片上限
+ * @returns {Uint8Array[]} 分片帧列表
  */
-export function encodeFrames(msgId, bytes, maxChunkBytes = DEFAULT_MAX_FRAME_CHUNK_BYTES) {
-	const body = normalizeBytes(bytes)
-	const idBytes = normalizeMsgIdBytes(msgId)
+export function encodeFrames(frameId, bytes, maxChunkBytes = DEFAULT_MAX_FRAME_CHUNK_BYTES) {
+	const body = toBytes(bytes)
+	const idBytes = normalizeFrameIdBytes(frameId)
 	const chunkBytes = Math.max(256, Math.min(DEFAULT_MAX_MESSAGE_BYTES, Number(maxChunkBytes) || DEFAULT_MAX_FRAME_CHUNK_BYTES))
 	const total = Math.max(1, Math.ceil(body.byteLength / chunkBytes))
 	/** @type {Uint8Array[]} */
@@ -94,11 +60,10 @@ export function encodeFrames(msgId, bytes, maxChunkBytes = DEFAULT_MAX_FRAME_CHU
 		const end = Math.min(body.byteLength, start + chunkBytes)
 		const chunk = body.subarray(start, end)
 		const frame = new Uint8Array(FRAME_HEADER_BYTES + chunk.byteLength)
-		frame[0] = FRAME_VERSION
-		frame.set(idBytes, 1)
+		frame.set(idBytes, 0)
 		const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength)
-		view.setUint32(1 + FRAME_MSG_ID_BYTES, seq, false)
-		view.setUint32(1 + FRAME_MSG_ID_BYTES + 4, total, false)
+		view.setUint32(FRAME_ID_BYTES, seq, false)
+		view.setUint32(FRAME_ID_BYTES + 4, total, false)
 		frame.set(chunk, FRAME_HEADER_BYTES)
 		frames.push(frame)
 	}
@@ -106,26 +71,22 @@ export function encodeFrames(msgId, bytes, maxChunkBytes = DEFAULT_MAX_FRAME_CHU
 }
 
 /**
- * 解析单帧二进制数据。
- * @param {Uint8Array | ArrayBuffer | ArrayBufferView} frame 原始帧字节
- * @returns {{ version: number, msgId: string, seq: number, total: number, chunk: Uint8Array }} 帧字段
+ * 解析单帧头与 chunk。
+ * @param {Uint8Array | ArrayBuffer | ArrayBufferView} frame 原始帧
+ * @returns {{ frameId: string, seq: number, total: number, chunk: Uint8Array }} 帧字段
  */
 export function decodeFrame(frame) {
-	const bytes = normalizeBytes(frame)
+	const bytes = toBytes(frame)
 	if (bytes.byteLength < FRAME_HEADER_BYTES)
 		throw new Error('p2p: frame too short')
-	const version = bytes[0]
-	if (version !== FRAME_VERSION)
-		throw new Error(`p2p: unsupported frame version ${version}`)
-	const msgId = msgIdBytesToHex(bytes.subarray(1, 1 + FRAME_MSG_ID_BYTES))
+	const frameId = bytesToHex(bytes.subarray(0, FRAME_ID_BYTES))
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
-	const seq = view.getUint32(1 + FRAME_MSG_ID_BYTES, false)
-	const total = view.getUint32(1 + FRAME_MSG_ID_BYTES + 4, false)
+	const seq = view.getUint32(FRAME_ID_BYTES, false)
+	const total = view.getUint32(FRAME_ID_BYTES + 4, false)
 	if (!total || seq >= total)
 		throw new Error('p2p: invalid frame sequence')
 	return {
-		version,
-		msgId,
+		frameId,
 		seq,
 		total,
 		chunk: bytes.subarray(FRAME_HEADER_BYTES),
@@ -133,9 +94,8 @@ export function decodeFrame(frame) {
 }
 
 /**
- * 按序拼接多个 chunk 为完整消息体。
- * @param {Uint8Array[]} chunks 已排序的 chunk 数组
- * @returns {Uint8Array} 拼接后的消息体
+ * @param {Uint8Array[]} chunks 有序分片
+ * @returns {Uint8Array} 拼接结果
  */
 function concatChunks(chunks) {
 	const totalBytes = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0)
@@ -149,96 +109,81 @@ function concatChunks(chunks) {
 }
 
 /**
- * 创建分片消息重组器。
- * @param {{ maxMessageBytes?: number, maxPartials?: number, partialTimeoutMs?: number }} [options] 大小、并发分片数与超时配置
- * @returns {{ push: (frame: Uint8Array | ArrayBuffer | ArrayBufferView, now?: number) => Uint8Array | null, prune: (now?: number) => string[], clear: () => void, size: () => number }} 重组器 API
+ * 创建分片重组器（按 frameId 聚合，超时 prune）。
+ * @param {{ maxMessageBytes?: number, maxPartials?: number, partialTimeoutMs?: number }} [options] 上限与超时
+ * @returns {{ push: (frame: Uint8Array | ArrayBuffer | ArrayBufferView, now?: number) => Uint8Array | null, prune: (now?: number) => string[], clear: () => void, size: () => number }} 重组 API
  */
 export function createReassembler(options = {}) {
 	const maxMessageBytes = Math.max(1024, Number(options.maxMessageBytes) || DEFAULT_MAX_MESSAGE_BYTES)
 	const maxPartials = Math.max(1, Number(options.maxPartials) || DEFAULT_MAX_PARTIAL_MESSAGES)
 	const partialTimeoutMs = Math.max(1000, Number(options.partialTimeoutMs) || DEFAULT_PARTIAL_TIMEOUT_MS)
-	/** @type {Map<string, { total: number, chunks: Uint8Array[], seen: boolean[], bytes: number, firstSeenAt: number, lastSeenAt: number }>} */
+	/** @type {Map<string, { total: number, remaining: number, chunks: Uint8Array[], bytes: number, firstSeenAt: number, lastSeenAt: number }>} */
 	const partials = new Map()
 
-	/**
-	 * 丢弃指定 msgId 的分片状态。
-	 * @param {string} msgId 消息 ID
-	 * @returns {void}
-	 */
-	function drop(msgId) {
-		partials.delete(msgId)
-	}
-
 	return {
 		/**
-		 * 喂入一帧，收齐全部分片时返回完整消息体。
-		 * @param {Uint8Array | ArrayBuffer | ArrayBufferView} frame 原始帧字节
-		 * @param {number} [now=Date.now()] 当前时间戳（毫秒）
-		 * @returns {Uint8Array | null} 完整消息体，未收齐时返回 null
+		 * 喂入一帧；凑齐则返回完整消息，否则 null。
+		 * @param {Uint8Array | ArrayBuffer | ArrayBufferView} frame 原始帧
+		 * @param {number} [now] 当前时间戳（测试可注入）
+		 * @returns {Uint8Array | null} 完整消息或尚未齐
 		 */
 		push(frame, now = Date.now()) {
 			const parsed = decodeFrame(frame)
-			if (!partials.has(parsed.msgId) && partials.size >= maxPartials)
+			if (!partials.has(parsed.frameId) && partials.size >= maxPartials)
 				throw new Error('p2p: too many partial messages')
-			let partial = partials.get(parsed.msgId)
+			let partial = partials.get(parsed.frameId)
 			if (!partial) {
 				partial = {
 					total: parsed.total,
+					remaining: parsed.total,
 					chunks: new Array(parsed.total),
-					seen: new Array(parsed.total).fill(false),
 					bytes: 0,
 					firstSeenAt: now,
 					lastSeenAt: now,
 				}
-				partials.set(parsed.msgId, partial)
+				partials.set(parsed.frameId, partial)
 			}
 			if (partial.total !== parsed.total) {
-				drop(parsed.msgId)
+				partials.delete(parsed.frameId)
 				throw new Error('p2p: frame total mismatch')
 			}
 			partial.lastSeenAt = now
-			if (!partial.seen[parsed.seq]) {
+			if (!partial.chunks[parsed.seq]) {
 				partial.chunks[parsed.seq] = parsed.chunk
-				partial.seen[parsed.seq] = true
+				partial.remaining--
 				partial.bytes += parsed.chunk.byteLength
 				if (partial.bytes > maxMessageBytes) {
-					drop(parsed.msgId)
+					partials.delete(parsed.frameId)
 					throw new Error('p2p: reassembled message exceeds limit')
 				}
 			}
-			if (partial.seen.every(Boolean)) {
+			if (partial.remaining === 0) {
 				const out = concatChunks(partial.chunks)
-				drop(parsed.msgId)
+				partials.delete(parsed.frameId)
 				return out
 			}
 			return null
 		},
 		/**
-		 * 清理超时的分片消息。
-		 * @param {number} [now=Date.now()] 当前时间戳（毫秒）
-		 * @returns {string[]} 被丢弃的 msgId 列表
+		 * 丢弃超时未齐的分片。
+		 * @param {number} [now] 当前时间戳
+		 * @returns {string[]} 被丢弃的 frameId 列表
 		 */
 		prune(now = Date.now()) {
 			/** @type {string[]} */
 			const expired = []
-			for (const [msgId, partial] of partials.entries())
+			for (const [frameId, partial] of partials)
 				if (now - partial.lastSeenAt > partialTimeoutMs) {
-					expired.push(msgId)
-					partials.delete(msgId)
+					expired.push(frameId)
+					partials.delete(frameId)
 				}
 			return expired
 		},
-		/**
-		 * 清空所有进行中的分片状态。
-		 * @returns {void}
-		 */
+		/** @returns {void} */
 		clear() {
 			partials.clear()
 		},
-		/**
-		 * 返回当前进行中的分片消息数量。
-		 * @returns {number} 分片 msgId 数量
-		 */
+		/** @returns {number} 进行中的分片消息数 */
 		size() {
 			return partials.size
 		},

package/link/handshake.mjs

@@ -51,7 +51,7 @@ export function buildAuthMessage(peerNonce, localBinding, localNodeHash) {
 /**
  * 构造 link hello 握手包。
  * @param {{ nodeHash?: string, nodePubKey?: string, nonce?: string }} [options] 可选身份字段，省略则从本地节点种子推导
- * @returns {{ v: 1, nodeHash: string, nodePubKey: string, nonce: string }} hello 对象
+ * @returns {{ nodeHash: string, nodePubKey: string, nonce: string }} hello 对象
  */
 export function buildHello(options = {}) {
 	let publicKey = null
@@ -66,7 +66,7 @@ export function buildHello(options = {}) {
 		throw new Error('p2p: invalid hello fields')
 	if (pubKeyHash(Buffer.from(nodePubKey, 'hex')) !== nodeHash)
 		throw new Error('p2p: hello nodePubKey does not match nodeHash')
-	return { v: 1, nodeHash, nodePubKey, nonce }
+	return { nodeHash, nodePubKey, nonce }
 }
 
 /**
@@ -92,13 +92,12 @@ export async function buildAuth(peerNonce, localBinding, options = {}) {
 /**
  * 解析并校验 hello 对象，无效时返回 null。
  * @param {unknown} hello 原始 hello 载荷
- * @returns {{ v: 1, nodeHash: string, nodePubKey: string, nonce: string } | null} 规范化 hello 或 null
+ * @returns {{ nodeHash: string, nodePubKey: string, nonce: string } | null} 规范化 hello 或 null
  */
 export function parseHello(hello) {
 	const nodeHash = normalizeHex64(hello?.nodeHash)
 	const nodePubKey = normalizeHex64(hello?.nodePubKey)
 	const nonce = normalizeHex64(hello?.nonce)
-	if (Number(hello?.v) !== 1) return null
 	if (!isHex64(nodeHash) || !isHex64(nodePubKey) || !isHex64(nonce)) return null
 	try {
 		if (pubKeyHash(Buffer.from(nodePubKey, 'hex')) !== nodeHash) return null
@@ -106,7 +105,7 @@ export function parseHello(hello) {
 	catch {
 		return null
 	}
-	return { v: 1, nodeHash, nodePubKey, nonce }
+	return { nodeHash, nodePubKey, nonce }
 }
 
 /**
@@ -136,26 +135,26 @@ export async function verifyAuth(hello, auth, expectedNonce, remoteBinding) {
 
 /**
  * 构造 discovery advert 待签名字节串。
- * @param {string} topic 广播主题
+ * @param {string} rendezvousKey discovery 内部汇合键
  * @param {number} ts 时间戳（毫秒）
  * @param {string} nodeHash 节点 nodeHash
  * @param {number | null} [tcpPort=null] 可选 LAN TCP 监听端口（签入消息）
  * @returns {Uint8Array} 待签名消息字节
  */
-export function buildAdvertMessage(topic, ts, nodeHash, tcpPort = null) {
-	const base = `fount-advert\0${String(topic)}\0${String(ts)}\0${normalizeHex64(nodeHash)}`
+export function buildAdvertMessage(rendezvousKey, ts, nodeHash, tcpPort = null) {
+	const base = `fount-advert\0${String(rendezvousKey)}\0${String(ts)}\0${normalizeHex64(nodeHash)}`
 	const port = normalizeTcpPort(tcpPort)
-	return Buffer.from(port == null ? base : `${base}\0${port}`, 'utf8')
+	return Buffer.from(port ? `${base}\0${port}` : base, 'utf8')
 }
 
 /**
  * 构造带签名的 discovery advert。
- * @param {string} topic 广播主题
+ * @param {string} rendezvousKey discovery 内部汇合键
  * @param {number} [ts=Date.now()] 时间戳（毫秒）
  * @param {{ secretKey?: Uint8Array, nodeHash?: string, nodePubKey?: string, tcpPort?: number } | null} [options] 签名身份与可选 tcpPort
  * @returns {Promise<{ nodeHash: string, nodePubKey: string, ts: number, sig: string, tcpPort?: number }>} 签名 advert
  */
-export async function buildSignedAdvert(topic, ts = Date.now(), options = null) {
+export async function buildSignedAdvert(rendezvousKey, ts = Date.now(), options = null) {
 	const seed = options?.secretKey
 		? Buffer.from(options.secretKey)
 		: Buffer.from(ensureNodeSeed(), 'hex')
@@ -165,9 +164,9 @@ export async function buildSignedAdvert(topic, ts = Date.now(), options = null)
 	if (pubKeyHash(Buffer.from(nodePubKey, 'hex')) !== nodeHash)
 		throw new Error('p2p: advert nodePubKey does not match nodeHash')
 	const tcpPort = normalizeTcpPort(options?.tcpPort)
-	if (options?.tcpPort != null && options.tcpPort !== '' && tcpPort == null)
+	if (options?.tcpPort && !tcpPort)
 		throw new Error('p2p: advert tcpPort invalid')
-	const message = buildAdvertMessage(topic, ts, nodeHash, tcpPort)
+	const message = buildAdvertMessage(rendezvousKey, ts, nodeHash, tcpPort)
 	const sig = await sign(message, secretKey)
 	const advert = {
 		nodeHash,
@@ -175,28 +174,28 @@ export async function buildSignedAdvert(topic, ts = Date.now(), options = null)
 		ts,
 		sig: Buffer.from(sig).toString('hex'),
 	}
-	if (tcpPort != null) advert.tcpPort = tcpPort
+	if (tcpPort) advert.tcpPort = tcpPort
 	return advert
 }
 
 /**
  * 验证 discovery advert 签名与时间戳，成功返回发布者 nodeHash。
- * @param {string} topic 期望的广播主题
+ * @param {string} rendezvousKey 期望的汇合键
  * @param {unknown} advert 原始 advert 载荷
  * @param {number} [now=Date.now()] 当前时间（毫秒）
  * @param {number} [maxSkewMs=10 * 60_000] 允许的最大时钟偏差（毫秒）
  * @returns {Promise<string | null>} 验证通过的 nodeHash，失败返回 null
  */
-export async function verifySignedAdvert(topic, advert, now = Date.now(), maxSkewMs = 10 * 60_000) {
-	const parsedHello = parseHello({ v: 1, nodeHash: advert?.nodeHash, nodePubKey: advert?.nodePubKey, nonce: '0'.repeat(64) })
+export async function verifySignedAdvert(rendezvousKey, advert, now = Date.now(), maxSkewMs = 10 * 60_000) {
+	const parsedHello = parseHello({ nodeHash: advert?.nodeHash, nodePubKey: advert?.nodePubKey, nonce: '0'.repeat(64) })
 	if (!parsedHello) return null
 	const ts = Number(advert?.ts)
 	const sig = String(advert?.sig ?? '').trim().toLowerCase()
 	if (!Number.isFinite(ts) || Math.abs(now - ts) > maxSkewMs || !/^[\da-f]{128}$/u.test(sig)) return null
-	const hasTcpPortField = advert?.tcpPort != null && advert.tcpPort !== ''
+	const hasTcpPortField = !!advert?.tcpPort
 	const tcpPort = normalizeTcpPort(advert?.tcpPort)
-	if (hasTcpPortField && tcpPort == null) return null
-	const message = buildAdvertMessage(topic, ts, parsedHello.nodeHash, tcpPort)
+	if (hasTcpPortField && !tcpPort) return null
+	const message = buildAdvertMessage(rendezvousKey, ts, parsedHello.nodeHash, tcpPort)
 	const ok = await verify(Buffer.from(sig, 'hex'), message, Buffer.from(parsedHello.nodePubKey, 'hex'))
 	return ok ? parsedHello.nodeHash : null
 }

package/link/pipe.mjs

@@ -1,46 +1,20 @@
+import { toBytes } from '../core/bytes_codec.mjs'
 import { normalizeHex64 } from '../core/hexIds.mjs'
 import { ms } from '../utils/duration.mjs'
+import { emitSafe } from '../utils/emit_safe.mjs'
 import { createLruMap } from '../utils/lru.mjs'
 
-import { createReassembler, encodeFrames, randomMsgIdHex } from './frame.mjs'
+import { createReassembler, encodeFrames, randomFrameIdHex } from './frame.mjs'
 import { buildAuth, buildHello, parseHello, verifyAuth } from './handshake.mjs'
 
 const encoder = new TextEncoder()
 const decoder = new TextDecoder()
 
-/**
- * 依次调用监听器集合，忽略单个 listener 抛错。
- * @param {Set<Function>} listeners 监听器集合
- * @param {...unknown} args 传递给 listener 的参数
- * @returns {void}
- */
-function emitListeners(listeners, ...args) {
-	for (const listener of listeners)
-		try { listener(...args) }
-		catch { /* ignore */ }
-}
-
-/**
- * 原始字节：以 `{` 开头的 UTF-8 当 control 文本，否则当二进制帧。
- * @param {Buffer | Uint8Array | string} raw 原始数据
- * @returns {string | Uint8Array} control 文本或二进制帧
- */
-export function coercePipeInbound(raw) {
-	if (typeof raw === 'string') return raw
-	const bytes = raw instanceof Uint8Array ? raw : Uint8Array.from(raw)
-	try {
-		const text = decoder.decode(bytes)
-		if (text.startsWith('{')) return text
-	}
-	catch { /* binary */ }
-	return bytes
-}
-
 /**
  * 把 createLinkPipe 句柄收成上层 LinkHandle（可附带测试/内部字段）。
- * @param {ReturnType<typeof createLinkPipe>} pipe pipe
- * @param {object} [extras] 附加字段（如 handleInbound、_channelForTest）
- * @returns {object} LinkHandle 形状
+ * @param {ReturnType<typeof createLinkPipe>} pipe pipe 句柄
+ * @param {object} [extras] 额外字段（覆盖同名）
+ * @returns {object} LinkHandle
  */
 export function asLinkHandle(pipe, extras = {}) {
 	return {
@@ -54,26 +28,26 @@ export function asLinkHandle(pipe, extras = {}) {
 		/** @returns {number} 提供者 level */
 		get level() { return pipe.level },
 		/**
-		 * @param {...unknown} args send 参数
-		 * @returns {Promise<boolean>} 是否发送成功
+		 * @param {...any} callArguments 透传 send
+		 * @returns {ReturnType<typeof pipe.send>} 是否发送成功
 		 */
-		send: (...args) => pipe.send(...args),
+		send: (...callArguments) => pipe.send(...callArguments),
 		/**
-		 * @param {...unknown} args onEnvelope 参数
-		 * @returns {() => void} 取消订阅
+		 * @param {...any} callArguments 透传 onEnvelope
+		 * @returns {ReturnType<typeof pipe.onEnvelope>} 取消订阅
 		 */
-		onEnvelope: (...args) => pipe.onEnvelope(...args),
+		onEnvelope: (...callArguments) => pipe.onEnvelope(...callArguments),
 		/**
-		 * @param {...unknown} args onDown 参数
-		 * @returns {() => void} 取消订阅
+		 * @param {...any} callArguments 透传 onDown
+		 * @returns {ReturnType<typeof pipe.onDown>} 取消订阅
 		 */
-		onDown: (...args) => pipe.onDown(...args),
+		onDown: (...callArguments) => pipe.onDown(...callArguments),
 		/**
-		 * @param {...unknown} args close 参数
-		 * @returns {Promise<void>}
+		 * @param {...any} callArguments 透传 close
+		 * @returns {ReturnType<typeof pipe.close>} 关闭完成
 		 */
-		close: (...args) => pipe.close(...args),
-		/** @returns {object} 运行时统计 */
+		close: (...callArguments) => pipe.close(...callArguments),
+		/** @returns {ReturnType<typeof pipe.stats>} 运行时统计 */
 		stats: () => pipe.stats(),
 		...extras,
 	}
@@ -99,8 +73,7 @@ export function asLinkHandle(pipe, extras = {}) {
  * @returns {object} link 句柄 + 入站 API
  */
 export function createLinkPipe(options) {
-	const providerId = String(options.providerId || '')
-	const level = Number(options.level) || 0
+	const { providerId, level } = options
 	const heartbeatMs = Number(options.heartbeatMs) || ms('15s')
 	const idleTimeoutMs = Number(options.idleTimeoutMs) || ms('45s')
 	const handshakeTimeoutMs = Number(options.handshakeTimeoutMs) || ms('10s')
@@ -125,7 +98,7 @@ export function createLinkPipe(options) {
 	let recvFrames = 0
 	const envelopeListeners = new Set()
 	const downListeners = new Set()
-	const completedMsgIds = createLruMap(4096)
+	const completedFrameIds = createLruMap(4096)
 	const reassembler = createReassembler()
 	/** @type {(value: void | PromiseLike<void>) => void} */
 	let resolveReady
@@ -219,9 +192,9 @@ export function createLinkPipe(options) {
 			remoteHello = parsed
 			await maybeSendAuth()
 			if (pendingAuth) {
-				const bufferedAuth = pendingAuth
+				const auth = pendingAuth
 				pendingAuth = null
-				await handleAuth(bufferedAuth)
+				await handleAuth(auth)
 			}
 			return
 		}
@@ -240,9 +213,9 @@ export function createLinkPipe(options) {
 			const merged = reassembler.push(bytes)
 			if (!merged) return
 			const envelope = JSON.parse(decoder.decode(merged))
-			const msgId = envelope?.msgId ? String(envelope.msgId) : null
-			if (msgId && completedMsgIds.has(msgId)) return
-			if (msgId) completedMsgIds.touch(msgId, true)
+			const frameId = typeof envelope.frameId === 'string' ? envelope.frameId : null
+			if (frameId && completedFrameIds.has(frameId)) return
+			if (frameId) completedFrameIds.touch(frameId, true)
 			if (envelope?.scope === 'link') {
 				if (envelope.action === 'ping') {
 					void send({ scope: 'link', action: 'pong', payload: {} }).catch(() => { })
@@ -251,7 +224,7 @@ export function createLinkPipe(options) {
 				if (envelope.action === 'pong') return
 			}
 			if (ready && remoteNodeHash)
-				emitListeners(envelopeListeners, envelope, remoteNodeHash)
+				emitSafe(envelopeListeners, envelope, remoteNodeHash)
 		}
 		catch {
 			/* drop malformed network ingress */
@@ -278,23 +251,22 @@ export function createLinkPipe(options) {
 			catch { /* ignore */ }
 			return
 		}
-		if (data instanceof ArrayBuffer || ArrayBuffer.isView(data) || data instanceof Uint8Array) {
-			const bytes = data instanceof Uint8Array
-				? data
-				: data instanceof ArrayBuffer
-					? new Uint8Array(data)
-					: new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
-			// 尝试 UTF-8 JSON control
-			try {
-				const text = decoder.decode(bytes)
-				if (text.startsWith('{')) {
-					void handleControlMessage(JSON.parse(text))
-					return
-				}
+		let bytes
+		try {
+			bytes = toBytes(data)
+		}
+		catch {
+			return
+		}
+		try {
+			const text = decoder.decode(bytes)
+			if (text.startsWith('{')) {
+				void handleControlMessage(JSON.parse(text))
+				return
 			}
-			catch { /* binary path */ }
-			handleBinaryFrame(bytes)
 		}
+		catch { /* binary path */ }
+		handleBinaryFrame(bytes)
 	}
 
 	/**
@@ -318,15 +290,17 @@ export function createLinkPipe(options) {
 	async function send(envelope) {
 		await readyPromise
 		if (closed) return false
-		const message = {
-			scope: String(envelope?.scope || ''),
-			action: String(envelope?.action || ''),
-			payload: envelope?.payload ?? null,
-			msgId: randomMsgIdHex(),
-		}
-		const bytes = encoder.encode(JSON.stringify(message))
-		for (const frame of encodeFrames(message.msgId, bytes)) {
-			await Promise.resolve(options.sendFrame(message.action, frame))
+		const frameId = randomFrameIdHex()
+		const bytes = encoder.encode(JSON.stringify({
+			scope: envelope.scope,
+			action: envelope.action,
+			payload: envelope.payload ?? null,
+			frameId,
+		}))
+		for (const frame of encodeFrames(frameId, bytes)) {
+			const sent = options.sendFrame(envelope.action, frame)
+			if (sent != null && typeof /** @type {{ then?: unknown }} */ sent.then === 'function')
+				await sent
 			sentFrames++
 		}
 		lastOutboundAt = Date.now()
@@ -347,7 +321,7 @@ export function createLinkPipe(options) {
 		if (idleTimer) clearInterval(idleTimer)
 		try { await Promise.resolve(options.closeTransport?.()) } catch { /* ignore */ }
 		if (!ready) rejectReady(new Error(`p2p: link closed before ready (${reason})`))
-		emitListeners(downListeners, reason)
+		emitSafe(downListeners, reason)
 	}
 
 	return {