@steve02081504/fount-p2p 0.0.12 → 0.0.13

package/files/assemble.mjs

@@ -147,18 +147,18 @@ export async function encryptPlaintextToMultiPartsAsync(plaintext, ceMode = 'con
 }
 
 /**
- * @param {object} params 参数
- * @param {string} params.ownerEntityHash 128 hex
- * @param {string} params.logicalPath EVFS 路径
- * @param {Buffer | Uint8Array} params.plaintext 明文
- * @param {string} [params.name] 文件名
- * @param {string} [params.mimeType] MIME
- * @param {CeMode} [params.ceMode] 加密模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
- * @param {object} [params.meta] 元数据
+ * @param {object} parameters 参数
+ * @param {string} parameters.ownerEntityHash 128 hex
+ * @param {string} parameters.logicalPath EVFS 路径
+ * @param {Buffer | Uint8Array} parameters.plaintext 明文
+ * @param {string} [parameters.name] 文件名
+ * @param {string} [parameters.mimeType] MIME
+ * @param {CeMode} [parameters.ceMode] 加密模式
+ * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {object} [parameters.meta] 元数据
  * @returns {FileManifest} manifest（未写盘）
  */
-export function buildFileManifest(params) {
+export function buildFileManifest(parameters) {
 	const {
 		ownerEntityHash,
 		logicalPath,
@@ -168,7 +168,7 @@ export function buildFileManifest(params) {
 		ceMode = 'convergent',
 		transferKeyDescriptor,
 		meta,
-	} = params
+	} = parameters
 	const enc = encryptPlaintextToParts(plaintext, ceMode)
 	const manifest = normalizeFileManifest({
 		ownerEntityHash: ownerEntityHash.toLowerCase(),
@@ -188,11 +188,11 @@ export function buildFileManifest(params) {
 
 /**
  * 由已加密分块构建 manifest（vault / file-master-key-wrap 等需自定义 transferKeyDescriptor）。
- * @param {object} params 与 buildFileManifest 相同字段（不含 plaintext 重加密）
+ * @param {object} parameters 与 buildFileManifest 相同字段（不含 plaintext 重加密）
  * @param {{ contentHash: string, parts: Array<{ hash: string, size: number, raw?: Buffer, contentHash?: string }> }} enc 加密结果
  * @returns {FileManifest} manifest
  */
-export function buildFileManifestFromEnc(params, enc) {
+export function buildFileManifestFromEnc(parameters, enc) {
 	const {
 		ownerEntityHash,
 		logicalPath,
@@ -202,7 +202,7 @@ export function buildFileManifestFromEnc(params, enc) {
 		ceMode = 'convergent',
 		transferKeyDescriptor,
 		meta,
-	} = params
+	} = parameters
 	const manifest = normalizeFileManifest({
 		ownerEntityHash: ownerEntityHash.toLowerCase(),
 		logicalPath: logicalPath.replace(/^\/+/, ''),

package/files/assemble_stream.mjs

@@ -44,11 +44,11 @@ export async function encryptReadableToParts(readable, ceMode = 'convergent', on
 	}
 
 	for await (const chunk of readable) {
-		const buf = Buffer.from(chunk)
-		total += buf.length
+		const buffer = Buffer.from(chunk)
+		total += buffer.length
 		if (total > maxBytes)
 			throw new Error('plaintext exceeds max upload size')
-		pending = Buffer.concat([pending, buf])
+		pending = Buffer.concat([pending, buffer])
 		while (pending.length >= FEDERATION_CHUNK_MAX_BYTES) {
 			const slice = pending.subarray(0, FEDERATION_CHUNK_MAX_BYTES)
 			pending = pending.subarray(FEDERATION_CHUNK_MAX_BYTES)
@@ -91,11 +91,11 @@ function readStreamChunk(stream) {
 			resolve(null)
 		}
 		/**
-		 * @param {Error} err 错误
+		 * @param {Error} error 错误
 		 */
-		const onError = err => {
+		const onError = error => {
 			cleanup()
-			reject(err)
+			reject(error)
 		}
 		/**
 		 *

package/files/chunk_responder.mjs

@@ -44,27 +44,36 @@ export async function handleFedManifestDataIngress(data) {
 
 /**
  * node scope user-room wire：注册 fed_chunk_* + fed_manifest_*。
- * @param {string} username 副本用户名 用户名
- * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire action 表
- * @returns {void}
+ * @param {string | (() => string)} usernameOrGetter 副本用户名或 live getter
+ * @param {{ on: (name: string, handler: (payload: unknown, peerId: string) => void) => (() => void) | void, send: (name: string, payload: unknown, peerId: string | null) => void }} wire action 表
+ * @returns {() => void} 取消挂载的 dispose
  */
-export function attachNodeScopeFedChunkResponder(username, wire) {
-	wire.on('fed_chunk_get', (data, peerId) => {
-		void handleFedChunkGetIngress(username, data, peerId, (resp, pid) => {
-			try { wire.send('fed_chunk_data', resp, pid) }
-			catch { /* disconnected */ }
-		})
-	})
-	wire.on('fed_chunk_data', handleFedChunkDataIngress)
-	wire.on('fed_manifest_get', (data, peerId) => {
-		void handleFedManifestGetIngress(username, data, peerId, (resp, pid) => {
-			try { wire.send('fed_manifest_data', resp, pid) }
-			catch { /* disconnected */ }
-		})
-	})
-	wire.on('fed_manifest_data', data => {
-		void handleFedManifestDataIngress(data)
-	})
+export function attachNodeScopeFedChunkResponder(usernameOrGetter, wire) {
+	const resolveUsername = typeof usernameOrGetter === 'function'
+		? usernameOrGetter
+		: () => usernameOrGetter
+	const offs = [
+		wire.on('fed_chunk_get', (data, peerId) => {
+			void handleFedChunkGetIngress(resolveUsername(), data, peerId, (resp, pid) => {
+				try { wire.send('fed_chunk_data', resp, pid) }
+				catch { /* disconnected */ }
+			})
+		}),
+		wire.on('fed_chunk_data', handleFedChunkDataIngress),
+		wire.on('fed_manifest_get', (data, peerId) => {
+			void handleFedManifestGetIngress(resolveUsername(), data, peerId, (resp, pid) => {
+				try { wire.send('fed_manifest_data', resp, pid) }
+				catch { /* disconnected */ }
+			})
+		}),
+		wire.on('fed_manifest_data', data => {
+			void handleFedManifestDataIngress(data)
+		}),
+	]
+	return () => {
+		for (const off of offs)
+			try { off?.() } catch { /* ignore */ }
+	}
 }
 
 /**

package/files/evfs.mjs

@@ -128,18 +128,18 @@ export async function readManifestPlaintextStream(replicaUsername, manifest, opt
 }
 
 /**
- * @param {object} params 参数
- * @param {string} params.ownerEntityHash owner
- * @param {string} params.logicalPath 路径
- * @param {Buffer | Uint8Array} params.plaintext 明文
- * @param {string} [params.name] 文件名
- * @param {string} [params.mimeType] MIME
- * @param {import('./manifest.mjs').CeMode} [params.ceMode] 模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
- * @param {object} [params.meta] meta
+ * @param {object} parameters 参数
+ * @param {string} parameters.ownerEntityHash owner
+ * @param {string} parameters.logicalPath 路径
+ * @param {Buffer | Uint8Array} parameters.plaintext 明文
+ * @param {string} [parameters.name] 文件名
+ * @param {string} [parameters.mimeType] MIME
+ * @param {import('./manifest.mjs').CeMode} [parameters.ceMode] 模式
+ * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {object} [parameters.meta] meta
  * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
  */
-export async function putFileManifest(params) {
+export async function putFileManifest(parameters) {
 	const {
 		ownerEntityHash,
 		logicalPath,
@@ -149,15 +149,15 @@ export async function putFileManifest(params) {
 		ceMode = 'convergent',
 		transferKeyDescriptor,
 		meta,
-	} = params
-	const plainBuf = Buffer.from(plaintext)
-	const enc = plainBuf.length > FEDERATION_CHUNK_MAX_BYTES
-		? await encryptPlaintextToMultiPartsAsync(plainBuf, ceMode)
-		: encryptPlaintextToParts(plainBuf, ceMode)
+	} = parameters
+	const plaintextBuffer = Buffer.from(plaintext)
+	const enc = plaintextBuffer.length > FEDERATION_CHUNK_MAX_BYTES
+		? await encryptPlaintextToMultiPartsAsync(plaintextBuffer, ceMode)
+		: encryptPlaintextToParts(plaintextBuffer, ceMode)
 	const manifest = buildFileManifestFromEnc({
 		ownerEntityHash,
 		logicalPath,
-		plaintext: plainBuf,
+		plaintext: plaintextBuffer,
 		name,
 		mimeType,
 		ceMode,
@@ -171,19 +171,19 @@ export async function putFileManifest(params) {
 
 /**
  * 流式写入文件（请求流 -> 加密分块 -> chunk store）。
- * @param {object} params 参数
- * @param {string} params.ownerEntityHash owner
- * @param {string} params.logicalPath 路径
- * @param {import('node:stream').Readable} params.readable 明文流
- * @param {number} params.plainSize 明文字节数
- * @param {string} [params.name] 文件名
- * @param {string} [params.mimeType] MIME
- * @param {import('./manifest.mjs').CeMode} [params.ceMode] 模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [params.transferKeyDescriptor] 传递密钥
- * @param {object} [params.meta] meta
+ * @param {object} parameters 参数
+ * @param {string} parameters.ownerEntityHash owner
+ * @param {string} parameters.logicalPath 路径
+ * @param {import('node:stream').Readable} parameters.readable 明文流
+ * @param {number} parameters.plainSize 明文字节数
+ * @param {string} [parameters.name] 文件名
+ * @param {string} [parameters.mimeType] MIME
+ * @param {import('./manifest.mjs').CeMode} [parameters.ceMode] 模式
+ * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {object} [parameters.meta] meta
  * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
  */
-export async function putFileManifestFromStream(params) {
+export async function putFileManifestFromStream(parameters) {
 	const {
 		ownerEntityHash,
 		logicalPath,
@@ -194,7 +194,7 @@ export async function putFileManifestFromStream(params) {
 		ceMode = 'convergent',
 		transferKeyDescriptor,
 		meta,
-	} = params
+	} = parameters
 	const enc = await encryptReadableToParts(readable, ceMode, async part =>
 		putChunk(part.hash, part.raw), plainSize)
 	const manifest = normalizeFileManifest({
@@ -228,6 +228,7 @@ export async function readPublicFile(replicaUsername, entityHash, logicalPath, o
 		username: options.username || replicaUsername,
 		ownerEntityHash: entityHash,
 		logicalPath,
+		cache: true,
 	})
 	if (!manifest) return null
 	return readManifestPlaintext(replicaUsername, manifest, options)

package/files/manifest_fetch.mjs

@@ -16,8 +16,9 @@ import { normalizeFileManifest } from './manifest.mjs'
 import { shouldPreferIncomingPublicManifest } from './public_manifest.mjs'
 
 /**
- * @param {{ username: string, ownerEntityHash: string, logicalPath: string }} context 上下文
- * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签后的公开清单
+ * 拉取公开 manifest；默认不写盘。`cache: true` 或 `cachePublicManifest` 才缓存。
+ * @param {{ username: string, ownerEntityHash: string, logicalPath: string, cache?: boolean }} context - 拉取上下文
+ * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签后的 manifest，失败为 null
  */
 export async function fetchPublicManifest(context) {
 	const ownerEntityHash = String(context.ownerEntityHash || '').trim().toLowerCase()
@@ -48,10 +49,22 @@ export async function fetchPublicManifest(context) {
 	const result = await done
 	if (!result) return null
 
-	await maybeCacheIncomingPublicManifest(ownerEntityHash, logicalPath, result)
+	if (context.cache === true)
+		await cachePublicManifest(ownerEntityHash, logicalPath, result)
 	return result
 }
 
+/**
+ * 将已验签公开 manifest 写入本地缓存（显式 apply；`fetchPublicManifest` 默认不调用）。
+ * @param {string} ownerEntityHash owner
+ * @param {string} logicalPath 路径
+ * @param {import('./manifest.mjs').FileManifest} incoming 已验签入站清单
+ * @returns {Promise<void>}
+ */
+export async function cachePublicManifest(ownerEntityHash, logicalPath, incoming) {
+	await maybeCacheIncomingPublicManifest(ownerEntityHash, logicalPath, incoming)
+}
+
 /**
  * @param {string} ownerEntityHash owner
  * @param {string} logicalPath 路径

package/files/public_manifest.mjs

@@ -116,18 +116,18 @@ export function shouldPreferIncomingPublicManifest(localManifest, incoming) {
 }
 
 /**
- * @param {object} params 参数
- * @param {string} params.ownerEntityHash owner
- * @param {string} params.logicalPath 路径
- * @param {Buffer | Uint8Array} params.plaintext 明文
- * @param {string} [params.name] 文件名
- * @param {string} [params.mimeType] MIME
- * @param {Uint8Array | Buffer} params.entitySecretKey recovery 私钥种子
- * @param {string} params.entityPubKeyHex recovery 公钥 hex
- * @param {number} [params.publishedAt] 发布时间（默认 Date.now）
+ * @param {object} parameters 参数
+ * @param {string} parameters.ownerEntityHash owner
+ * @param {string} parameters.logicalPath 路径
+ * @param {Buffer | Uint8Array} parameters.plaintext 明文
+ * @param {string} [parameters.name] 文件名
+ * @param {string} [parameters.mimeType] MIME
+ * @param {Uint8Array | Buffer} parameters.entitySecretKey recovery 私钥种子
+ * @param {string} parameters.entityPubKeyHex recovery 公钥 hex
+ * @param {number} [parameters.publishedAt] 发布时间（默认 Date.now）
  * @returns {Promise<import('./manifest.mjs').FileManifest>} 已签名并落盘的公开清单
  */
-export async function publishPublicFile(params) {
+export async function publishPublicFile(parameters) {
 	const {
 		ownerEntityHash,
 		logicalPath,
@@ -137,7 +137,7 @@ export async function publishPublicFile(params) {
 		entitySecretKey,
 		entityPubKeyHex,
 		publishedAt = Date.now(),
-	} = params
+	} = parameters
 	const base = await putFileManifest({
 		ownerEntityHash,
 		logicalPath,

package/files/transfer_key_registry.mjs

@@ -90,8 +90,8 @@ export async function readDagManifestPlaintext(replicaUsername, manifest) {
 		const reader = dagPlaintextReadersByOwner.get(ownerId)
 		if (reader)
 			try {
-				const buf = await reader(replicaUsername, manifest)
-				if (buf?.length) return buf
+				const buffer = await reader(replicaUsername, manifest)
+				if (buffer?.length) return buffer
 			}
 			catch { /* fall through */ }
 		return null

package/index.mjs

@@ -1,40 +1,115 @@
 /**
  * Federation P2P 门面：fount 网络引导与房间/发现入口。
- * 上层只面对 nodeHash + envelope，不选择 WebRTC/BLE 等传输。
- * 重型子系统请从子路径导入（如 `./dag`）；勿导入未导出的 `link/`。
  */
 import { registerDiscoveryProvider } from './discovery/index.mjs'
+import {
+	isInfraRunning,
+	setInfraPriority,
+	startInfra,
+	stopInfra,
+} from './infra/service.mjs'
+import { registerLinkProvider } from './link/providers/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
-import { getNodeDir, initNode, isNodeInitialized } from './node/instance.mjs'
+import {
+	getNodeDir,
+	initNode,
+	isNodeInitialized,
+	setNodeLogger,
+	setSignalingRuntimeConfig,
+} from './node/instance.mjs'
+import { setConnectivityDebug } from './node/log.mjs'
+import {
+	attachReputationSyncWire,
+	getReputationExportAllowlist,
+	getReputationLocks,
+	getReputationTable,
+	getTrustSyncDonors,
+	lockReputationMax,
+	pullReputationFromNode,
+	setReputationExportAllowlist,
+	setReputationTable,
+	setTrustSyncDonors,
+	unlockReputationMax,
+} from './node/reputation_sync.mjs'
+import { getRoutingProfile, setRoutingProfile } from './node/routing_profile.mjs'
 import { createScopedLinkRoom } from './rooms/scoped_link.mjs'
 import { createGroupLinkSet } from './transport/group_link_set.mjs'
-import { getLinkRegistry } from './transport/link_registry.mjs'
-import { ensureUserRoom } from './transport/user_room.mjs'
+import {
+	configureLinkRegistry,
+	ensureLinkToNode,
+	ensureOverlayRouter,
+	getLinkRegistry,
+	reloadDiscoveryRelays,
+	sendToNodeLink,
+} from './transport/link_registry.mjs'
+import {
+	attachUserRoomDefaultWires,
+	ensureNodeScope,
+	ensureUserRoom,
+	getUserRoomSlot,
+} from './transport/user_room.mjs'
 
 /**
- *
+ * 包门面：节点、infra、mesh/registry、信誉同步、node-scope 等公开导出。
  */
 export {
+	attachReputationSyncWire,
+	attachUserRoomDefaultWires,
+	configureLinkRegistry,
 	createGroupLinkSet,
 	createScopedLinkRoom,
+	ensureLinkToNode,
 	ensureNodeDefaults,
+	ensureNodeScope,
+	ensureOverlayRouter,
 	ensureUserRoom,
 	getLinkRegistry,
 	getNodeDir,
 	getNodeHash,
+	getReputationExportAllowlist,
+	getReputationLocks,
+	getReputationTable,
+	getRoutingProfile,
+	getTrustSyncDonors,
+	getUserRoomSlot,
 	initNode,
+	isInfraRunning,
 	isNodeInitialized,
+	lockReputationMax,
+	pullReputationFromNode,
 	registerDiscoveryProvider,
+	registerLinkProvider,
+	reloadDiscoveryRelays,
+	sendToNodeLink,
+	setConnectivityDebug,
+	setInfraPriority,
+	setNodeLogger,
+	setReputationExportAllowlist,
+	setReputationTable,
+	setRoutingProfile,
+	setSignalingRuntimeConfig,
+	setTrustSyncDonors,
+	startInfra,
+	stopInfra,
+	unlockReputationMax,
 }
 
 /**
- * 初始化并启动 P2P 节点运行时（身份、链路网、link registry）。
- * @param {{ nodeDir: string, entityStore?: import('./node/entity_store.mjs').EntityStore, logger?: object, signaling?: import('./node/signaling_config.mjs').SignalingRuntimeConfig }} options 节点配置
+ * @param {{ nodeDir?: string, entityStore?: import('./node/entity_store.mjs').EntityStore, logger?: object | null, signaling?: import('./node/signaling_config.mjs').SignalingRuntimeConfig }} [options] - 首次 init 时的节点选项
  * @returns {Promise<void>}
  */
-export async function startNode(options) {
-	if (!isNodeInitialized())
-		initNode(options)
+export async function startNode(options = {}) {
+	if (!isNodeInitialized()) {
+		const { nodeDir, entityStore, logger, signaling, ...rest } = options
+		if (Object.keys(rest).length)
+			throw new Error('p2p: startNode unknown options')
+		initNode({ nodeDir, entityStore })
+		if (logger !== undefined) setNodeLogger(logger)
+		if (signaling !== undefined) setSignalingRuntimeConfig(signaling)
+	}
+	else if (options?.nodeDir || options?.entityStore || options?.logger !== undefined || options?.signaling)
+		throw new Error('p2p: startNode options ignored after initNode — use setNodeLogger / setSignalingRuntimeConfig')
+
 	ensureNodeDefaults()
 	await getLinkRegistry().ensureRuntime()
 }

package/infra/cli.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { on_shutdown } from 'on-shutdown'
+
+import { ensureNodeDefaults, getNodeHash } from '../node/identity.mjs'
+import { initNode, setNodeLogger } from '../node/instance.mjs'
+import { setConnectivityDebug } from '../node/log.mjs'
+import { getLinkRegistry } from '../transport/link_registry.mjs'
+
+import { resolveNodeDir } from './default_node_dir.mjs'
+import { setInfraPriority, startInfra, stopInfra } from './service.mjs'
+
+/**
+ * @param {string[]} argv - 命令行参数（不含 node 路径）
+ * @returns {{ nodeDir?: string, quiet?: boolean, useLocalReputation?: boolean, help?: boolean }} 解析结果
+ */
+function parseArgs(argv) {
+	/** @type {ReturnType<typeof parseArgs>} */
+	const out = {}
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		if (arg === '--help' || arg === '-h') out.help = true
+		else if (arg === '--quiet') out.quiet = true
+		else if (arg === '--use-local-reputation') out.useLocalReputation = true
+		else if (arg === '--node-dir') out.nodeDir = argv[++i]
+	}
+	return out
+}
+
+/** 打印 CLI 用法。 */
+function printHelp() {
+	console.log(`Usage: fount-p2p [--node-dir PATH] [--use-local-reputation] [--quiet]
+
+Public-good infra relay node (overlay + mailbox).
+Connectivity debug logs on by default (Nostr/LAN/mesh/dial); --quiet silences.
+Non-CLI shells: setConnectivityDebug(true).
+Default data dir: Windows %LOCALAPPDATA%/fount-p2p/node, else ~/.local/share/fount-p2p/node`)
+}
+
+const args = parseArgs(process.argv.slice(2))
+if (args.help) {
+	printHelp()
+	process.exit(0)
+}
+
+const nodeDir = resolveNodeDir(args.nodeDir)
+initNode({ nodeDir })
+if (args.quiet) {
+	setNodeLogger(null)
+	setConnectivityDebug(false)
+}
+else
+	setConnectivityDebug(true)
+ensureNodeDefaults()
+const nodeHash = getNodeHash()
+await getLinkRegistry().ensureRuntime()
+if (args.useLocalReputation) setInfraPriority({ useLocalReputation: true })
+await startInfra({ logger: args.quiet ? null : console })
+
+console.log(`p2p infra running (nodeDir=${nodeDir} nodeHash=${nodeHash})`)
+
+on_shutdown(stopInfra)

package/infra/debug_log.mjs

@@ -0,0 +1,56 @@
+import { getLinkRegistry } from '../transport/link_registry.mjs'
+
+/** @type {Array<() => void>} */
+const cleanups = []
+
+/**
+ * 挂载 registry link/overlay/node scope 调试日志。
+ * @param {{ info?: Function, warn?: Function, error?: Function, log?: Function } | null} logger - 日志输出目标，null 表示静默
+ * @returns {() => void} 取消 debug 监听的 dispose
+ */
+export function attachInfraDebugLog(logger) {
+	detachInfraDebugLog()
+	if (!logger) return () => { }
+	const registry = getLinkRegistry()
+	/**
+	 * @param {'info' | 'warn' | 'error' | 'log'} level - 日志级别
+	 * @param {string} message - 日志消息
+	 * @param {object} [extra] - 附加字段
+	 */
+	const log = (level, message, extra) => {
+		logger?.[level]?.(message, extra)
+	}
+	cleanups.push(registry.onLinkUp((nodeHash, link) => {
+		log('info', 'p2p:infra link up', {
+			nodeHash,
+			providerId: link?.providerId,
+			level: link?.level,
+		})
+	}))
+	cleanups.push(registry.onLinkDown((nodeHash, reason) => {
+		log('info', 'p2p:infra link down', { nodeHash, reason })
+	}))
+	cleanups.push(registry.subscribeScope('overlay', (from, envelope) => {
+		log('info', 'p2p:infra overlay', {
+			from,
+			action: envelope?.action,
+			path: envelope?.payload?.path,
+		})
+	}))
+	cleanups.push(registry.subscribeScope('node', (from, envelope) => {
+		log('info', 'p2p:infra node', {
+			from,
+			action: envelope?.action,
+		})
+	}))
+	return detachInfraDebugLog
+}
+
+/**
+ * 卸掉 infra debug 监听。
+ * @returns {void}
+ */
+export function detachInfraDebugLog() {
+	for (const cleanup of cleanups.splice(0))
+		try { cleanup() } catch { /* ignore */ }
+}

package/infra/default_node_dir.mjs

@@ -0,0 +1,22 @@
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * @returns {string} 平台默认 node 数据目录
+ */
+export function defaultNodeDir() {
+	if (process.platform === 'win32') {
+		const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')
+		return path.join(base, 'fount-p2p', 'node')
+	}
+	return path.join(os.homedir(), '.local', 'share', 'fount-p2p', 'node')
+}
+
+/**
+ * @param {string | undefined} override - CLI 或调用方覆盖
+ * @returns {string} 解析后的绝对 node 目录
+ */
+export function resolveNodeDir(override) {
+	const trimmed = String(override || '').trim()
+	return trimmed ? path.resolve(trimmed) : defaultNodeDir()
+}

package/infra/priority.mjs

@@ -0,0 +1,56 @@
+import { normalizeHex64 } from '../core/hexIds.mjs'
+import { getReputationTable } from '../node/reputation_sync.mjs'
+import { pickNodeScoreFromReputation } from '../reputation/pick_score.mjs'
+import { getLinkRegistry } from '../transport/link_registry.mjs'
+
+
+/** @type {{ useLocalReputation: boolean }} */
+let priorityConfig = { useLocalReputation: false }
+
+const PRIORITY_BOOST = 1000
+
+/**
+ * 配置 infra 路由加权（是否用本地 reputation）。
+ * @param {{ useLocalReputation?: boolean }} config - 是否用本地 reputation 加权路由
+ * @returns {void}
+ */
+export function setInfraPriority(config = {}) {
+	priorityConfig = {
+		useLocalReputation: Boolean(config.useLocalReputation),
+	}
+	applyPriorityToRegistry()
+}
+
+/**
+ * @returns {{ useLocalReputation: boolean }} 当前 priority 配置副本
+ */
+export function getInfraPriority() {
+	return { ...priorityConfig }
+}
+
+/**
+ * @returns {void}
+ */
+export function applyPriorityToRegistry() {
+	const registry = getLinkRegistry()
+	if (!priorityConfig.useLocalReputation) {
+		registry.setPriorityWeightFunction(null)
+		return
+	}
+	registry.setPriorityWeightFunction(nodeHash => {
+		const score = pickNodeScoreFromReputation(
+			getReputationTable(),
+			normalizeHex64(nodeHash) || nodeHash,
+		)
+		return Math.floor(score * PRIORITY_BOOST)
+	})
+}
+
+/**
+ * stopInfra：卸 weight，并重置 priority 配置，避免再次 startInfra 幽灵恢复加权。
+ * @returns {void}
+ */
+export function clearInfraPriorityFromRegistry() {
+	priorityConfig = { useLocalReputation: false }
+	getLinkRegistry().setPriorityWeightFunction(null)
+}