@steve02081504/fount-p2p 0.0.0

package/trust_graph/build.mjs

@@ -0,0 +1,99 @@
+import { isPeerKeyBlocked, isSubjectBlocked } from '../node/denylist.mjs'
+import { loadNetwork } from '../node/network.mjs'
+import { loadReputation } from '../node/reputation_store.mjs'
+import { listFederationRoomSlots } from '../registries/room_provider.mjs'
+import { isQuarantinedPure } from '../reputation/engine.mjs'
+import { ensureUserRoom } from '../transport/user_room.mjs'
+
+import { getCachedTrustGraph } from './cache.mjs'
+import { mergeGraph, pickTopFromGraph } from './engine.mjs'
+import trustGraphTunables from './tunables.json' with { type: 'json' }
+
+/**
+ * @typedef {import('./engine.mjs').TrustNode} TrustNode
+ */
+
+/**
+ * @param {string} nodeHash 64 位十六进制
+ * @returns {boolean} 是否拉黑
+ */
+function isNodeBlocked(nodeHash) {
+	return isPeerKeyBlocked('', nodeHash) || isSubjectBlocked({ nodeHash })
+}
+
+/**
+ * @param {string} username 副本用户名 登录名（联邦房间枚举仍按用户）
+ * @returns {Promise<Map<string, TrustNode>>} nodeHash → 节点
+ */
+export async function buildMergedGraph(username) {
+	return getCachedTrustGraph(username, async () => {
+		const net = loadNetwork()
+		const rep = loadReputation()
+		const blocked = new Set()
+		const quarantined = new Set()
+		for (const nodeHash of [...net.trustedPeers, ...net.explorePeers, ...net.hints.map(h => h.nodeHash)]) {
+			if (isNodeBlocked(nodeHash)) blocked.add(nodeHash)
+			if (isQuarantinedPure(rep, nodeHash)) quarantined.add(nodeHash)
+		}
+
+		/**
+		 * @param {string} nodeHash 64 位十六进制
+		 * @returns {number} 信誉分
+		 */
+		function scoreOf(nodeHash) {
+			return Number(rep.byNodeHash?.[nodeHash]?.score ?? 0)
+		}
+
+		const rooms = await listFederationRoomSlots(username)
+		/** @type {import('./engine.mjs').TrustGraphInputs['roomRosters']} */
+		const roomRosters = []
+		for (const room of rooms) {
+			const nodeHashes = []
+			for (const { remoteNodeHash } of room.getRoster()) {
+				if (!remoteNodeHash) continue
+				if (isNodeBlocked(remoteNodeHash)) blocked.add(remoteNodeHash)
+				else if (isQuarantinedPure(rep, remoteNodeHash)) quarantined.add(remoteNodeHash)
+				else nodeHashes.push(remoteNodeHash)
+			}
+			/**
+			 * @param {string} remoteNodeHash 64 位十六进制
+			 * @returns {number} 本地主观信誉分；从未打分的新人退回 rosterDefaultScore
+			 */
+			function rosterScoreOf(remoteNodeHash) {
+				const row = rep.byNodeHash?.[remoteNodeHash]
+				return row && Number.isFinite(Number(row.score))
+					? Number(row.score)
+					: trustGraphTunables.rosterDefaultScore
+			}
+			roomRosters.push({
+				scopeId: room.groupId,
+				nodeHashes,
+				scoreOf: rosterScoreOf,
+			})
+		}
+
+		return mergeGraph({
+			trustedPeers: net.trustedPeers,
+			explorePeers: net.explorePeers,
+			hints: net.hints,
+			roomRosters,
+			blockedNodeHashes: blocked,
+			quarantinedNodeHashes: quarantined,
+			scoreOf,
+		})
+	})
+}
+
+/**
+ * @param {string} username 副本用户名 登录名
+ * @param {number} [limit=12] 最多返回节点数
+ * @returns {Promise<TrustNode[]>} 按信誉降序
+ */
+export async function pickTopNodes(username, limit = trustGraphTunables.pickTopNodesDefaultLimit) {
+	await ensureUserRoom({ replicaUsername: username })
+	const rep = loadReputation()
+	const quarantined = new Set(
+		Object.keys(rep.byNodeHash || {}).filter(id => isQuarantinedPure(rep, id)),
+	)
+	return pickTopFromGraph(await buildMergedGraph(username), limit, trustGraphTunables, quarantined)
+}

package/trust_graph/cache.mjs

@@ -0,0 +1,44 @@
+/** @type {Map<string, { graph: Map<string, object>, builtAt: number, revision: number }>} */
+const cacheByUsername = new Map()
+let revision = 0
+
+const DEFAULT_TTL_MS = 30_000
+
+/**
+ * @returns {number} 当前 revision
+ */
+export function getTrustGraphRevision() {
+	return revision
+}
+
+/**
+ * @returns {void}
+ */
+export function invalidateTrustGraphCache() {
+	cacheByUsername.clear()
+	revision++
+}
+
+/**
+ * @param {string} username 副本用户名 登录名（缓存键，与 buildMergedGraph 一致）
+ * @param {() => Promise<Map<string, object>>} build 构建函数
+ * @param {number} [ttlMs=30000] TTL
+ * @returns {Promise<Map<string, object>>} 合并后的信任图
+ */
+export async function getCachedTrustGraph(username, build, ttlMs = DEFAULT_TTL_MS) {
+	const key = String(username || '')
+	const now = Date.now()
+	const cached = cacheByUsername.get(key)
+	if (cached && cached.revision === revision && now - cached.builtAt < ttlMs)
+		return cached.graph
+
+	const graph = await build()
+	cacheByUsername.set(key, { graph, builtAt: now, revision })
+	return graph
+}
+
+/** @returns {void} 测试用 */
+export function clearTrustGraphCache() {
+	cacheByUsername.clear()
+	revision = 0
+}

package/trust_graph/engine.mjs

@@ -0,0 +1,184 @@
+/**
+ * TrustGraph 纯图合并/选择（模拟器与 trust_graph.mjs 共用）。
+ */
+import { resolveFederationFanoutTopK } from './resolve.mjs'
+import trustGraphTunables from './tunables.json' with { type: 'json' }
+
+/**
+ * @typedef {{ nodeHash: string, score: number, scopeIds: string[] }} TrustNode
+ * @typedef {{
+ *   trustedPeers?: string[],
+ *   explorePeers?: string[],
+ *   hints?: Array<{ nodeHash: string, source?: string, weight?: number, expiresAt?: number }>,
+ *   roomRosters?: Array<{ scopeId: string, nodeHashes: string[], scoreOf?: (nodeHash: string) => number }>,
+ *   blockedNodeHashes?: Set<string>,
+ *   quarantinedNodeHashes?: Set<string>,
+ *   now?: number,
+ * }} TrustGraphInputs
+ */
+
+/**
+ * @returns {typeof trustGraphTunables} 默认 tunables
+ */
+export function defaultTrustGraphTunables() {
+	return trustGraphTunables
+}
+
+/**
+ * @param {Map<string, TrustNode>} byNode 累积图
+ * @param {string} scopeId scope 标识
+ * @param {string} nodeHash 64 位十六进制
+ * @param {number} score 信誉分
+ */
+export function mergeTrustNode(byNode, scopeId, nodeHash, score) {
+	const previous = byNode.get(nodeHash)
+	if (previous) {
+		const seenCount = previous.scopeIds.length
+		previous.score = (previous.score * seenCount + score) / (seenCount + 1)
+		if (!previous.scopeIds.includes(scopeId)) previous.scopeIds.push(scopeId)
+		return
+	}
+	byNode.set(nodeHash, { nodeHash, score, scopeIds: [scopeId] })
+}
+
+/**
+ * @param {TrustGraphInputs} inputs 图输入
+ * @param {typeof trustGraphTunables} [tunables] tunables
+ * @returns {Map<string, TrustNode>} nodeHash → 节点
+ */
+export function mergeGraph(inputs, tunables = trustGraphTunables) {
+	/**
+	 * @typedef {{
+	 *   scopeIds: Set<string>,
+	 *   networkScores: number[],
+	 *   rosterScores: number[],
+	 *   hintWeightSum: number,
+	 *   hintSources: Set<string>,
+	 * }} NodeEvidence
+	 */
+	/** @type {Map<string, NodeEvidence>} */
+	const evidenceByNode = new Map()
+	const blocked = inputs.blockedNodeHashes || new Set()
+	const quarantined = inputs.quarantinedNodeHashes || new Set()
+	const damp = Number(tunables.quarantineTrustDamp ?? 0.35)
+	const now = inputs.now ?? Date.now()
+	/**
+	 * @param {string} nodeHash 64 位十六进制
+	 * @returns {boolean} 是否拉黑
+	 */
+	function isBlocked(nodeHash) {
+		return blocked.has(nodeHash)
+	}
+
+	/**
+	 * @param {string} nodeHash 64 位十六进制
+	 * @returns {boolean} 是否本地隔离
+	 */
+	function isQuarantined(nodeHash) {
+		return quarantined.has(nodeHash)
+	}
+
+	/**
+	 * @param {string} nodeHash 64 位十六进制
+	 * @returns {NodeEvidence} 节点证据容器
+	 */
+	function nodeEvidence(nodeHash) {
+		let ev = evidenceByNode.get(nodeHash)
+		if (!ev) {
+			ev = {
+				scopeIds: new Set(),
+				networkScores: [],
+				rosterScores: [],
+				hintWeightSum: 0,
+				hintSources: new Set(),
+			}
+			evidenceByNode.set(nodeHash, ev)
+		}
+		return ev
+	}
+
+	for (const nodeHash of [...inputs.trustedPeers || [], ...inputs.explorePeers || []]) {
+		if (isBlocked(nodeHash)) continue
+		const score = inputs.scoreOf?.(nodeHash) ?? 0
+		const ev = nodeEvidence(nodeHash)
+		ev.scopeIds.add('network')
+		ev.networkScores.push(Number(score))
+	}
+
+	for (const hint of inputs.hints || []) {
+		if (hint.expiresAt && hint.expiresAt <= now) continue
+		if (isBlocked(hint.nodeHash)) continue
+		const ev = nodeEvidence(hint.nodeHash)
+		ev.scopeIds.add(`hint:${hint.source ?? 'unknown'}`)
+		const rawWeight = Number(hint.weight ?? tunables.hintDefaultWeight)
+		if (Number.isFinite(rawWeight) && rawWeight > 0)
+			ev.hintWeightSum += rawWeight
+		ev.hintSources.add(String(hint.source ?? 'unknown'))
+	}
+
+	for (const room of inputs.roomRosters || [])
+		for (const remoteNodeHash of room.nodeHashes) {
+			if (!remoteNodeHash || isBlocked(remoteNodeHash)) continue
+			// 名册只能告诉你「这个节点存在于该 scope」；信任分一律取本地主观信誉，
+			// 仅当本地从未给它打过分（新人）时才退回 rosterDefaultScore。
+			const local = room.scoreOf?.(remoteNodeHash) ?? inputs.scoreOf?.(remoteNodeHash)
+			const score = Number.isFinite(Number(local)) ? Number(local) : tunables.rosterDefaultScore
+			const ev = nodeEvidence(remoteNodeHash)
+			ev.scopeIds.add(room.scopeId)
+			ev.rosterScores.push(score)
+		}
+
+	/** @type {Map<string, TrustNode>} */
+	const byNode = new Map()
+	for (const [nodeHash, ev] of evidenceByNode.entries()) {
+		const networkMean = ev.networkScores.length
+			? ev.networkScores.reduce((s, n) => s + n, 0) / ev.networkScores.length
+			: NaN
+		const rosterMean = ev.rosterScores.length
+			? ev.rosterScores.reduce((s, n) => s + n, 0) / ev.rosterScores.length
+			: NaN
+		const baseScores = [networkMean, rosterMean].filter(Number.isFinite)
+		const baseScore = baseScores.length
+			? baseScores.reduce((s, n) => s + n, 0) / baseScores.length
+			: 0
+
+		// Hint 只做“发现增益”：收益按总权重指数饱和，防止多源投毒线性抬分。
+		const hintScale = 0.1
+		const saturatedHintLift = tunables.hintMaxBonus * (1 - Math.exp(-ev.hintWeightSum / hintScale))
+		const hasHardEvidence = ev.networkScores.length + ev.rosterScores.length > 0
+		const hintReliability = hasHardEvidence ? 1 : 0.35
+		let score = baseScore + saturatedHintLift * hintReliability
+		if (isQuarantined(nodeHash))
+			score *= damp
+
+		byNode.set(nodeHash, { nodeHash, score, scopeIds: [...ev.scopeIds] })
+	}
+	return byNode
+}
+
+/**
+ * @param {Map<string, TrustNode>} graph 合并图
+ * @param {number} [limit] 最多返回节点数
+ * @param {typeof trustGraphTunables} [tunables] tunables
+ * @param {Set<string>} [quarantinedNodeHashes] 本地隔离节点（踢出 topK）
+ * @returns {TrustNode[]} 按信誉降序
+ */
+export function pickTopFromGraph(graph, limit = trustGraphTunables.pickTopNodesDefaultLimit, tunables = trustGraphTunables, quarantinedNodeHashes = new Set()) {
+	const k = limit ?? tunables.pickTopNodesDefaultLimit
+	return [...graph.values()]
+		.filter(node => !quarantinedNodeHashes.has(node.nodeHash))
+		.sort((a, b) => b.score - a.score)
+		.slice(0, Math.max(1, k))
+}
+
+/**
+ * @param {TrustGraphInputs} inputs 图输入
+ * @param {number} [limit] fanout K
+ * @param {typeof trustGraphTunables} [tunables] tunables
+ * @returns {TrustNode[]} Top-K 节点
+ */
+export function pickTop(inputs, limit, tunables = trustGraphTunables) {
+	const graph = mergeGraph(inputs, tunables)
+	const k = limit ?? resolveFederationFanoutTopK(graph.size, tunables)
+	return pickTopFromGraph(graph, k, tunables, inputs.quarantinedNodeHashes || new Set())
+}

package/trust_graph/registry.mjs

@@ -0,0 +1,38 @@
+import { buildMergedGraph, pickTopNodes } from './build.mjs'
+import { fanoutToTopNodes, sendToNode } from './send.mjs'
+
+/** @type {Map<string, import('./registry.mjs').TrustGraphProvider>} */
+const providersByOwner = new Map()
+
+/** 用户级 P2P trust graph（registerTrustGraphProvider 注册） */
+export const DEFAULT_TRUST_GRAPH_OWNER = 'default'
+
+/**
+ * @param {string} ownerId 注册方（如 chat）
+ * @param {import('./registry.mjs').TrustGraphProvider} impl 信任图实现
+ * @returns {void}
+ */
+export function registerTrustGraphProvider(ownerId, impl) {
+	providersByOwner.set(String(ownerId), impl)
+}
+
+/** @returns {void} */
+export function clearTrustGraphProvider() {
+	providersByOwner.clear()
+}
+
+/**
+ * @param {string} [ownerId=DEFAULT_TRUST_GRAPH_OWNER] 注册方 ID
+ * @returns {import('./registry.mjs').TrustGraphProvider} 已注册实现
+ */
+export function requireTrustGraphProvider(ownerId = DEFAULT_TRUST_GRAPH_OWNER) {
+	const impl = providersByOwner.get(String(ownerId))
+	if (!impl)
+		throw new Error(`p2p: registerTrustGraphProvider('${ownerId}') must run before trust graph fanout`)
+	return impl
+}
+
+/** @returns {import('./registry.mjs').TrustGraphProvider} 默认信任图实现 */
+export function createDefaultTrustGraphProvider() {
+	return { buildMergedGraph, pickTopNodes, sendToNode, fanoutToTopNodes }
+}

package/trust_graph/resolve.mjs

@@ -0,0 +1,105 @@
+/**
+ * 共享 tunables 缩放：ratio + floor + cap，仿真与运行时共用。
+ */
+
+/** @typedef {{ floor: number, ratio: number, cap?: number }} ScaleSpec */
+
+/**
+ * @param {number} n 分母（在场人数 / 候选 peer 数等）
+ * @param {ScaleSpec} spec floor、ratio、可选 cap
+ * @returns {number} 有效整数阈值 ≥ floor
+ */
+export function scaleCount(n, { floor, ratio, cap = Infinity }) {
+	const safeN = Math.max(0, Math.floor(Number(n) || 0))
+	const scaled = Math.ceil(safeN * Number(ratio) || 0)
+	const capped = Number.isFinite(cap) ? Math.min(scaled, Math.floor(cap)) : scaled
+	const bounded = safeN > 0 ? Math.min(capped, safeN) : Math.max(1, Math.floor(floor))
+	return Math.max(Math.max(1, Math.floor(floor)), bounded)
+}
+
+/**
+ * @param {number} n 群 activeMembers 或联邦应答 peer 数
+ * @param {object} tunables 归档 tunables
+ * @returns {number} 收集阶段 quorum peerMin
+ */
+export function resolveArchiveQuorumPeerMin(n, tunables) {
+	return scaleCount(n, {
+		floor: tunables.archiveQuorumPeerMinFloor ?? tunables.archiveQuorumPeerMin ?? 2,
+		ratio: tunables.archiveQuorumPeerMinRatio ?? 0.25,
+	})
+}
+
+/**
+ * @param {number} n 群 activeMembers 或联邦应答 peer 数
+ * @param {object} tunables 归档 tunables
+ * @returns {number} 无正信誉时 strictMin（硬钳 ≥2）
+ */
+export function resolveArchiveQuorumPeerStrictMin(n, tunables) {
+	const raw = scaleCount(n, {
+		floor: tunables.archiveQuorumPeerStrictMinFloor ?? tunables.archiveQuorumPeerStrictMin ?? 2,
+		ratio: tunables.archiveQuorumPeerStrictMinRatio ?? 0.5,
+	})
+	return Math.max(2, raw)
+}
+
+/**
+ * @param {number} peerCount 已知在线 relay 候选数
+ * @param {object} tunables 邮箱 tunables
+ * @returns {number} 受信层 relay fanout
+ */
+export function resolveMailboxRelayFanout(peerCount, tunables) {
+	if (Number.isFinite(tunables.relayFanoutTrusted))
+		return Math.max(1, Math.min(peerCount > 0 ? peerCount : Infinity, Math.floor(tunables.relayFanoutTrusted)))
+	return scaleCount(peerCount, {
+		floor: tunables.relayFanoutTrustedFloor ?? 3,
+		ratio: tunables.relayFanoutTrustedRatio ?? 0.3,
+		cap: tunables.relayFanoutTrustedCap ?? 32,
+	})
+}
+
+/**
+ * @param {number} peerCount 已知在线 relay 候选数
+ * @param {object} tunables 邮箱 tunables
+ * @returns {number} want 广播 fanout
+ */
+export function resolveMailboxWantFanout(peerCount, tunables) {
+	if (Number.isFinite(tunables.wantFanout))
+		return Math.max(1, Math.min(peerCount > 0 ? peerCount : Infinity, Math.floor(tunables.wantFanout)))
+	return scaleCount(peerCount, {
+		floor: tunables.wantFanoutFloor ?? 3,
+		ratio: tunables.wantFanoutRatio ?? 0.4,
+		cap: tunables.wantFanoutCap ?? 32,
+	})
+}
+
+/**
+ * @param {number} rosterSize 信任图 roster 大小
+ * @param {object} tunables 信任图 tunables
+ * @returns {number} 联邦 fanout Top-K
+ */
+export function resolveFederationFanoutTopK(rosterSize, tunables) {
+	if (Number.isFinite(tunables.federationFanoutTopK))
+		return Math.max(1, Math.min(rosterSize > 0 ? rosterSize : Infinity, Math.floor(tunables.federationFanoutTopK)))
+	return scaleCount(rosterSize, {
+		floor: tunables.federationFanoutTopKFloor ?? 3,
+		ratio: tunables.federationFanoutTopKRatio ?? 0.35,
+		cap: tunables.federationFanoutTopKCap ?? 16,
+	})
+}
+
+/**
+ * @param {object} tunables 归档 tunables
+ * @param {number} [activeMemberCount] 群 active 成员数
+ * @param {number} [candidatePeerCount] 联邦候选 peer 数
+ * @returns {{ peerMin: number, strictMin: number }} 归档 quorum 阈值
+ */
+export function resolveArchiveQuorumThresholds(tunables, activeMemberCount, candidatePeerCount) {
+	const n = Math.max(
+		Number(activeMemberCount) || 0,
+		Number(candidatePeerCount) || 0,
+	)
+	return {
+		peerMin: resolveArchiveQuorumPeerMin(n, tunables),
+		strictMin: resolveArchiveQuorumPeerStrictMin(n, tunables),
+	}
+}

package/trust_graph/send.mjs

@@ -0,0 +1,88 @@
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { getNodeHash } from '../node/identity.mjs'
+import { loadReputation } from '../node/reputation_store.mjs'
+import { listFederationRoomSlots } from '../registries/room_provider.mjs'
+import { isQuarantinedPure } from '../reputation/engine.mjs'
+import { sendToNodeLink } from '../transport/link_registry.mjs'
+import { USER_ROOM_SCOPE } from '../transport/room_scopes.mjs'
+import { ensureUserRoom } from '../transport/user_room.mjs'
+
+import { buildMergedGraph } from './build.mjs'
+import { pickTopFromGraph } from './engine.mjs'
+import { resolveFederationFanoutTopK } from './resolve.mjs'
+import trustGraphTunables from './tunables.json' with { type: 'json' }
+
+/**
+ * @param {string} username 副本用户名 登录名
+ * @param {string} targetNodeHash 64 位十六进制
+ * @param {string} actionName Trystero 动作
+ * @param {unknown} payload 载荷
+ * @param {Map<string, object>} [graph] 已构建信任图（省略时内部构建）
+ * @returns {Promise<boolean>} 是否已发送
+ */
+export async function sendToNode(username, targetNodeHash, actionName, payload, graph) {
+	const target = normalizeHex64(targetNodeHash) || String(targetNodeHash || '').trim().toLowerCase()
+	if (!isHex64(target)) return false
+	await ensureUserRoom({ replicaUsername: username })
+
+	// 已直连 peer 不经 trust-graph scope 也应能收发 node scope action（非成员 CAS chunk / follow hint 等）
+	if (await sendToNodeLink(target, { scope: 'node', action: String(actionName), payload }))
+		return true
+
+	const merged = graph ?? await buildMergedGraph(username)
+	const targetNode = merged.get(target)
+	if (!targetNode?.scopeIds.length) return false
+	const selfNodeHash = getNodeHash()
+
+	const rooms = await listFederationRoomSlots(username)
+	const userRooms = rooms.filter(room => room.groupId === USER_ROOM_SCOPE)
+	const groupRooms = rooms.filter(room => room.groupId !== USER_ROOM_SCOPE)
+
+	for (const userRoom of userRooms) {
+		const peerId = userRoom.getPeerIdByNodeHash(target)
+		if (peerId) {
+			userRoom.sendToPeer(peerId, actionName, payload)
+			return true
+		}
+	}
+
+	for (const room of groupRooms) {
+		if (!targetNode.scopeIds.includes(room.groupId)) continue
+		const peerId = room.getPeerIdByNodeHash(targetNodeHash)
+		if (peerId) {
+			room.sendToPeer(peerId, actionName, payload)
+			return true
+		}
+		if (room.pickFallbackPeerIds) {
+			const targets = await room.pickFallbackPeerIds(selfNodeHash)
+			if (targets.length) {
+				for (const targetPeerId of targets.slice(0, trustGraphTunables.sendFallbackPeerLimit))
+					room.sendToPeer(targetPeerId, actionName, payload)
+				return true
+			}
+		}
+	}
+	return false
+}
+
+/**
+ * @param {string} username 副本用户名 登录名
+ * @param {string} actionName action 名
+ * @param {unknown} payload 载荷
+ * @param {number} [limit] K（省略时按 roster 规模缩放）
+ * @returns {Promise<number>} 发送次数
+ */
+export async function fanoutToTopNodes(username, actionName, payload, limit) {
+	await ensureUserRoom({ replicaUsername: username })
+	const graph = await buildMergedGraph(username)
+	const k = limit ?? resolveFederationFanoutTopK(graph.size, trustGraphTunables)
+	const rep = loadReputation()
+	const quarantined = new Set(
+		Object.keys(rep.byNodeHash || {}).filter(id => isQuarantinedPure(rep, id)),
+	)
+	const topNodes = pickTopFromGraph(graph, k, trustGraphTunables, quarantined)
+	let sent = 0
+	for (const { nodeHash } of topNodes)
+		if (await sendToNode(username, nodeHash, actionName, payload, graph)) sent++
+	return sent
+}

package/trust_graph/tunables.json

@@ -0,0 +1,13 @@
+{
+	"federationFanoutTopKFloor": 3,
+	"federationFanoutTopKRatio": 0.35,
+	"federationFanoutTopKCap": 16,
+	"federationChunkFetchFanoutK": 6,
+	"federationChunkMaxBytes": 524288,
+	"hintDefaultWeight": 0.1,
+	"hintMaxBonus": 0.15,
+	"rosterDefaultScore": 0.1,
+	"sendFallbackPeerLimit": 4,
+	"pickTopNodesDefaultLimit": 12,
+	"quarantineTrustDamp": 0.35
+}

package/utils/async_mutex.mjs

@@ -0,0 +1,69 @@
+/**
+ * 进程内 per-key 异步互斥锁（队列式，避免 Promise 链堆积）。
+ */
+
+/** @type {Map<string, { locked: boolean, queue: Array<() => void> }>} */
+const mutexes = new Map()
+
+/**
+ * @param {string} lockKey 锁键
+ * @returns {{ locked: boolean, queue: Array<() => void> }} 互斥状态
+ */
+function mutexState(lockKey) {
+	let state = mutexes.get(lockKey)
+	if (!state) {
+		state = { locked: false, queue: [] }
+		mutexes.set(lockKey, state)
+	}
+	return state
+}
+
+/**
+ * @param {string} lockKey 锁键
+ * @param {{ locked: boolean, queue: Array<() => void> }} state 互斥状态
+ * @returns {void}
+ */
+function releaseMutex(lockKey, state) {
+	const next = state.queue.shift()
+	if (next) setTimeout(next, 0)
+	else {
+		state.locked = false
+		mutexes.delete(lockKey)
+	}
+}
+
+/**
+ * @param {string} key 锁键
+ * @param {() => Promise<T>} fn 临界区
+ * @returns {Promise<T>} `fn` 的解析结果
+ * @template T
+ */
+export async function withAsyncMutex(key, fn) {
+	const lockKey = String(key)
+	const state = mutexState(lockKey)
+	return new Promise((resolve, reject) => {
+		/**
+		 * @returns {void}
+		 */
+		const run = () => {
+			Promise.resolve()
+				.then(fn)
+				.then(resolve, reject)
+				.finally(() => releaseMutex(lockKey, state))
+		}
+		if (state.locked) state.queue.push(run)
+		else {
+			state.locked = true
+			run()
+		}
+	})
+}
+
+/**
+ * @param {string} keyPrefix 前缀
+ * @returns {(key: string, fn: () => Promise<T>) => Promise<T>} 带前缀的 mutex 函数
+ * @template T
+ */
+export function asyncMutexForPrefix(keyPrefix) {
+	return (key, fn) => withAsyncMutex(`${keyPrefix}:${key}`, fn)
+}

package/utils/debug_log.mjs

@@ -0,0 +1,16 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const dir = path.resolve(process.cwd(), 'debug_logs')
+
+/**
+ * P2P 观测落盘：写入进程 cwd 下 `debug_logs/`（与 monorepo `debugLog` 行为对齐）。
+ * @param {string} name 日志文件名（不含扩展名）
+ * @param {unknown} data 调试数据
+ * @returns {Promise<void>}
+ */
+export async function debugLog(name, data) {
+	const text = Object(data) instanceof String ? data : JSON.stringify(data)
+	await fs.promises.mkdir(dir, { recursive: true })
+	await fs.promises.appendFile(path.join(dir, `${name}.log`), text)
+}

package/utils/duration.mjs

@@ -0,0 +1,28 @@
+/**
+ * 将持续时间字符串转换为毫秒。
+ * @param {string|number} duration - 持续时间字符串 (例如, "1d", "2h", "30m", "10s") 或毫秒数。
+ * @returns {number} 持续时间（以毫秒为单位）。
+ */
+export function ms(duration) {
+	if (Object(duration) instanceof Number) return duration
+
+	const match = /(\d+)\s*(\w+)/.exec(duration)
+	if (!match)
+		throw new Error('Invalid duration format')
+
+	const value = Number(match[1])
+	const unit = match[2]
+
+	switch (unit) {
+		case 's':
+			return value * 1000
+		case 'm':
+			return value * 60 * 1000
+		case 'h':
+			return value * 60 * 60 * 1000
+		case 'd':
+			return value * 24 * 60 * 60 * 1000
+		default:
+			throw new Error('Invalid duration unit')
+	}
+}