@steve02081504/fount-p2p 0.0.46 → 0.0.48

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.46",
+	"version": "0.0.48",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -25,7 +25,9 @@
 		"test:fount": "deno test -A --config deno.json test/fount/",
 		"test:live": "node --test --test-concurrency=1 --test-force-exit test/live/*.test.mjs",
 		"test:sim": "node --test --test-concurrency=1 --test-force-exit sim/test/*.test.mjs",
-		"test:frontend": "node --test --test-concurrency=1 --test-force-exit test/frontend/*.test.mjs"
+		"test:frontend": "node --test --test-concurrency=1 --test-force-exit test/frontend/*.test.mjs",
+		"test:checks": "node --test --test-concurrency=1 --test-force-exit test/pure/text_lf.test.mjs test/pure/jsdoc_no_english.test.mjs test/pure/agents_md_english.test.mjs",
+		"check:text_lf:fix": "node scripts/checks/text_lf.mjs --fix .."
 	},
 	"bin": {
 		"fount-p2p": "infra/cli.mjs"

package/sim/AGENTS.md

@@ -15,7 +15,7 @@ In-process co-evolution of **tunables** (`*.tunables.json`) against an **attack
 - **`PARAM_SPACE` ↔ defaults:** every `PARAM_SPACE` key must exist in `loadDefaultTunables()`; clear both sides when deleting a key.
 - **`socialRepHideThreshold`:** hide when `score < threshold`. Default `0` (suppress negatives only). Raise the threshold to raise `falsePositiveRate` — never use a negative threshold for "stricter".
 - **Heuristic proxy** (not the real path): `model.mjs`, `discovery.mjs`, `transport.mjs`, `integrity.mjs` — analytical "params → defense" only.
-- **Mesh-first:** explore slots and cold-start join are mandatory; fanout/trust stay separate from link presence. Policy: [docs/mesh.md](../docs/mesh.md). Wiring: [cold_start.md](cold_start.md).
+- **Mesh-first:** explore slots and cold-start join are mandatory; fanout/trust stay separate from link presence. Policy: [docs/mesh.md](../docs/mesh.md). Wiring: [docs/cold_start.md](docs/cold_start.md).
 
 ## Anti-drift
 

package/sim/{cold_start.md → docs/cold_start.md}

@@ -1,6 +1,6 @@
 # Sim cold-start (K = 0)
 
-Mesh policy: [docs/mesh.md](../docs/mesh.md). Day-to-day sim rules: [AGENTS.md](AGENTS.md).
+Mesh policy: [mesh.md](../../docs/mesh.md). Day-to-day sim rules: [AGENTS.md](../AGENTS.md).
 
 When the observer has no acquaintances (`trustedPeers=[]`), the sim must still join via discovery explore slots — not idle.
 

package/transport/link_registry.mjs

@@ -25,6 +25,24 @@ import { createRuntimeBootstrap } from './runtime_bootstrap.mjs'
 const DIAL_COOLDOWN_BASE_MS = ms('30s')
 /** dial 冷却上限。 */
 const DIAL_COOLDOWN_MAX_MS = ms('10m')
+/**
+ * 单次确保直连的整体上限：覆盖全部 provider 尝试（含 offer/answer 握手）后必须结算。
+ * 必须大于 nostr 入队 publish 等待上限，让「relay 连不上」走 provider 自身的失败路径，
+ * 而不是在这里被掐断（否则拿不到 provider 级诊断）。见 fount-p2p#37。
+ */
+export const LINK_DIAL_DEADLINE_MS = ms('90s')
+
+/** 测试可缩短的单次直连上限。 */
+let dialDeadlineMs = LINK_DIAL_DEADLINE_MS
+
+/**
+ * 覆盖单次直连上限（测试用；传 null 恢复默认）。
+ * @param {number | null} value 毫秒上限；null 恢复默认
+ * @returns {void}
+ */
+export function setLinkDialDeadlineMsForTests(value) {
+	dialDeadlineMs = value == null ? LINK_DIAL_DEADLINE_MS : value
+}
 
 /**
  * 解析或从节点种子推导本地身份。
@@ -263,8 +281,58 @@ export function createLinkRegistry(options = {}) {
 		return links.get(remoteNodeHash) ?? null
 	}
 
+	/**
+	 * 记一次 dial 失败并进入指数退避。
+	 * @param {string} normalized 远端节点 64 hex
+	 * @returns {number} 本次冷却毫秒
+	 */
+	function noteDialFailure(normalized) {
+		const failures = (dialCooldown.get(normalized)?.failures || 0) + 1
+		const delay = Math.min(DIAL_COOLDOWN_MAX_MS, DIAL_COOLDOWN_BASE_MS * (2 ** Math.min(failures - 1, 5)))
+		dialCooldown.touch(normalized, { until: Date.now() + delay, failures })
+		return delay
+	}
+
+	/**
+	 * 为一个已登记的直连尝试套上整体上限：超时即返回 null（调用方不再等），
+	 * 后台尝试照旧收敛，成功仍会注册链路。
+	 *
+	 * 超时后立刻从 inflights 摘除，后续 dial 走新尝试而不是复用这个卡住的 promise。
+	 * @param {string} normalized 远端节点 64 hex
+	 * @param {Promise<object | null>} task 进行中的 dial
+	 * @returns {Promise<object | null>} dial 结果；超时 null
+	 */
+	async function awaitDialAttempt(normalized, task) {
+		if (dialDeadlineMs <= 0) return await task
+		/** @type {boolean} */
+		let expired = false
+		/** @type {ReturnType<typeof setTimeout> | null} */
+		let timer = null
+		const timeout = new Promise(resolve => {
+			timer = setTimeout(() => {
+				expired = true
+				resolve(null)
+			}, dialDeadlineMs)
+			timer.unref?.()
+		})
+		const link = await Promise.race([task, timeout])
+		if (timer) clearTimeout(timer)
+		if (!expired) return link
+		// 超时：调用方不再等，但后台尝试仍会自行收敛（成功照样注册链路，失败自己记冷却）。
+		if (inflights.get(normalized) === task) inflights.delete(normalized)
+		const cooldownMs = noteDialFailure(normalized)
+		nodeDebug('p2p:dial deadline', {
+			peer: shortHash(normalized),
+			deadlineMs: dialDeadlineMs,
+			cooldownMs,
+		})
+		return null
+	}
+
 	/**
 	 * 按 level 降序尝试各 LinkProvider，不可用/不可达/失败则回落。
+	 * 整体有 LINK_DIAL_DEADLINE_MS 上限：卡住的 provider 既不能让调用方永久等待，
+	 * 也不能把坏 promise 留在 inflights 里毒化后续 dial。
 	 * @param {string} remoteNodeHash 远端节点 64 hex
 	 * @returns {Promise<object | null>} 链路实例；失败时 null
 	 */
@@ -274,7 +342,7 @@ export function createLinkRegistry(options = {}) {
 		const normalized = remoteNodeHash
 		if (!normalized || normalized === localIdentity.nodeHash) return null
 		if (links.has(normalized)) return links.get(normalized)
-		if (inflights.has(normalized)) return await inflights.get(normalized)
+		if (inflights.has(normalized)) return await awaitDialAttempt(normalized, inflights.get(normalized))
 		const cool = dialCooldown.get(normalized)
 		const now = Date.now()
 		if (cool) {
@@ -335,14 +403,12 @@ export function createLinkRegistry(options = {}) {
 					})
 				}
 
-			const failures = (cool?.failures || 0) + 1
-			const delay = Math.min(DIAL_COOLDOWN_MAX_MS, DIAL_COOLDOWN_BASE_MS * (2 ** Math.min(failures - 1, 5)))
-			dialCooldown.touch(normalized, { until: Date.now() + delay, failures })
-			nodeDebug('p2p:dial exhausted', { peer: shortHash(normalized), cooldownMs: delay, failures })
+			const cooldownMs = noteDialFailure(normalized)
+			nodeDebug('p2p:dial exhausted', { peer: shortHash(normalized), cooldownMs })
 			return null
 		})().finally(() => inflights.delete(normalized))
 		inflights.set(normalized, task)
-		return await task
+		return await awaitDialAttempt(normalized, task)
 	}
 
 	meshKeepalive = createMeshKeepalive({
@@ -387,9 +453,12 @@ export function createLinkRegistry(options = {}) {
 
 	/**
 	 * 启动 discovery/link runtime 并开启 mesh keepalive。
+	 * 顺带重启 peer health 订阅：`shutdown()` 会停掉它，重启运行时后必须重新挂上，
+	 * 否则 getPeerHealth / listPeerHealth 会永远为空（见 fount-p2p#38）。
 	 */
 	const ensureRuntimeWithMesh = async () => {
 		await bootstrap.ensureRuntime()
+		peerHealth.start()
 		meshKeepalive?.start()
 	}
 

package/transport/peer_health.mjs

@@ -19,6 +19,7 @@ import { emitSafe } from '../utils/emit_safe.mjs'
  *   getPeerHealth: (nodeHash: string) => PeerHealthEntry | null
  *   listPeerHealth: () => PeerHealthEntry[]
  *   onPeerHealth: (listener: (nodeHash: string, entry: PeerHealthEntry) => void) => () => void
+ *   start: () => void
  *   stop: () => void
  * }} peer health 聚合器
  */
@@ -29,6 +30,10 @@ export function createPeerHealthTracker(registry) {
 	const cleanups = new Map()
 	/** @type {Set<(nodeHash: string, entry: PeerHealthEntry) => void>} */
 	const listeners = new Set()
+	/** @type {(() => void) | null} registry link up 退订 */
+	let stopUp = null
+	/** @type {(() => void) | null} registry link down 退订 */
+	let stopDown = null
 
 	/**
 	 * 合并补丁并通知订阅方。
@@ -54,37 +59,48 @@ export function createPeerHealthTracker(registry) {
 		emitSafe(listeners, nodeHash, entry)
 	}
 
-	const stopUp = registry.onLinkUp?.((nodeHash, link) => {
-		if (!nodeHash) return
-		const stopRtt = link?.onRtt?.(() => {
-			const stats = link.stats?.() ?? {}
+	/**
+	 * 订阅 registry 的链路事件（幂等）。
+	 * `stop()` 之后可用它重新挂上监听：registry 的 link up/down 桶在 shutdown 时不会被清空，
+	 * 所以重启运行时后健康记录能自然恢复。
+	 * @returns {void}
+	 */
+	function start() {
+		if (stopUp) return
+		stopUp = registry.onLinkUp?.((nodeHash, link) => {
+			if (!nodeHash) return
+			const stopRtt = link?.onRtt?.(() => {
+				const stats = link.stats?.() ?? {}
+				update(nodeHash, {
+					rttMs: stats.rttMs ?? null,
+					avgRttMs: stats.avgRttMs ?? null,
+					lastSeenAt: Date.now(),
+				})
+			}) ?? null
+			const stopLinkDown = link?.onDown?.(() => {
+				cleanups.get(nodeHash)?.()
+				cleanups.delete(nodeHash)
+				update(nodeHash, { connected: false, lastSeenAt: Date.now() })
+			}) ?? null
 			update(nodeHash, {
-				rttMs: stats.rttMs ?? null,
-				avgRttMs: stats.avgRttMs ?? null,
+				connected: true,
+				source: link?.providerId ?? null,
 				lastSeenAt: Date.now(),
 			})
+			cleanups.set(nodeHash, () => {
+				stopRtt?.()
+				stopLinkDown?.()
+			})
 		}) ?? null
-		const stopDown = link?.onDown?.(() => {
+		stopDown = registry.onLinkDown?.(nodeHash => {
+			if (!nodeHash) return
 			cleanups.get(nodeHash)?.()
 			cleanups.delete(nodeHash)
 			update(nodeHash, { connected: false, lastSeenAt: Date.now() })
 		}) ?? null
-		update(nodeHash, {
-			connected: true,
-			source: link?.providerId ?? null,
-			lastSeenAt: Date.now(),
-		})
-		cleanups.set(nodeHash, () => {
-			stopRtt?.()
-			stopDown?.()
-		})
-	}) ?? null
-	const stopDown = registry.onLinkDown?.(nodeHash => {
-		if (!nodeHash) return
-		cleanups.get(nodeHash)?.()
-		cleanups.delete(nodeHash)
-		update(nodeHash, { connected: false, lastSeenAt: Date.now() })
-	}) ?? null
+	}
+
+	start()
 
 	return {
 		/**
@@ -108,17 +124,19 @@ export function createPeerHealthTracker(registry) {
 			listeners.add(listener)
 			return () => listeners.delete(listener)
 		},
+		start,
 		/**
-		 * 停止监听并清空聚合。
+		 * 停止监听并清空聚合（listen 订阅保留，listeners 订阅者保留）。
 		 * @returns {void}
 		 */
 		stop() {
 			stopUp?.()
 			stopDown?.()
+			stopUp = null
+			stopDown = null
 			for (const cleanup of cleanups.values()) cleanup()
 			cleanups.clear()
 			entries.clear()
-			listeners.clear()
 		},
 	}
 }

package/transport/runtime_bootstrap.mjs

@@ -28,6 +28,15 @@ import { createWebRtcLinkProvider } from '../link/providers/webrtc.mjs'
 import { getSignalingRuntimeConfig, onNodeChange } from '../node/instance.mjs'
 import { isConnectivityDebug, nodeDebug, shortHash } from '../node/log.mjs'
 
+/**
+ * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+ * @returns {boolean} 是否由本 registry 自己持有（lan_tcp / ble_gatt 走各自的快速监听路径）
+ */
+function providerIsRegistryOwned(provider) {
+	const { id } = provider
+	return id.startsWith('lan_tcp') || id.startsWith('ble_gatt')
+}
+
 /**
  * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
  * @returns {boolean} 是否使用原生 probe 路径
@@ -36,6 +45,16 @@ export function providerHasNativeProbe(provider) {
 	return provider.caps?.probe === 'native'
 }
 
+/**
+ * @param {import('../link/providers/index.mjs').LinkProvider} provider 链路提供者
+ * @returns {boolean} 是否需要在 runtime 暖机时补挂监听
+ */
+export function providerNeedsListening(provider) {
+	if (providerIsRegistryOwned(provider)) return false
+	if (providerHasNativeProbe(provider)) return false
+	return !!provider.ensureListening
+}
+
 /**
  * @param {import('../link/providers/index.mjs').LinkProvider | null} ownedLanTcp 本 registry 持有的 lan_tcp
  * @returns {import('../link/providers/index.mjs').LinkProvider[]} 可快速启动监听的 provider 列表
@@ -45,10 +64,8 @@ export function collectFastListenProviders(ownedLanTcp) {
 	const listenProviders = []
 	if (ownedLanTcp) listenProviders.push(ownedLanTcp)
 	for (const provider of listLinkProviders()) {
-		const { id } = provider
-		if (id.startsWith('lan_tcp') || id.startsWith('ble_gatt')) continue
-		if (!provider.ensureListening) continue
-		if (providerHasNativeProbe(provider)) continue
+		if (!providerNeedsListening(provider)) continue
+		// 快速路径只接同步 isAvailable：要等异步探测的 provider 交给 startEnabledProviderListening。
 		if (provider.isAvailable)
 			try {
 				const available = provider.isAvailable()
@@ -202,6 +219,24 @@ export function createRuntimeBootstrap(deps) {
 		return encryptAdvertForScope('network', localIdentity, body)
 	}
 
+	/**
+	 * 为所有「已注册、已启用、尚未监听」的 link provider 启动监听。
+	 * `reconcileLinkProviders()` 重新注册的 provider 只有走到这里才会拿到 onInbound/localIdentity，
+	 * 否则它会静默丢弃全部入站 link-open（见 fount-p2p#38）。
+	 *
+	 * 刻意不看 `isAvailable()`：relay 池为空/未探测时 nostr 的 `isAvailable()` 会是 false，而 relay 列表
+	 * 是在发送时解析的；先挂上监听才能收到入站 link-open，暂时不可用不该让它变哑巴。
+	 * @returns {Promise<void>}
+	 */
+	async function startEnabledProviderListening() {
+		if (!autoRegisterLinkProviders) return
+		await Promise.all(listLinkProviders()
+			.filter(provider => isChannelEnabled(provider.id.split(':')[0]))
+			.filter(provider => providerNeedsListening(provider))
+			.filter(provider => !stopLinkListeners.has(provider.id))
+			.map(provider => startProviderListening(provider)))
+	}
+
 	/**
 	 * @param {number} gen 启动世代
 	 * @returns {Promise<void>}
@@ -212,6 +247,8 @@ export function createRuntimeBootstrap(deps) {
 		signalListenReady = (async () => {
 			await lanListenReady.catch(() => { })
 			if (generation !== gen || !isLive()) return
+			await startEnabledProviderListening().catch(() => { })
+			if (generation !== gen || !isLive()) return
 			if (!listDiscoveryProviders().length) return
 			stopSignalListener = await listenNodeSignals(localIdentity.nodeHash, bytes => {
 				void handleIncomingSignal(bytes).catch(() => { })
@@ -324,11 +361,9 @@ export function createRuntimeBootstrap(deps) {
 			reconcileLinkProviders()
 			reconcileDiscoveryProviders()
 			if (generation !== gen || !isLive()) return
-			if (ownedLanTcp && !stopLinkListeners.has(ownedLanTcp.id))
-				await startProviderListening(ownedLanTcp)
-			if (ownedBleGatt && !stopLinkListeners.has(ownedBleGatt.id)
-				&& await Promise.resolve(ownedBleGatt.isAvailable()))
-				await startProviderListening(ownedBleGatt)
+			// 覆盖本轮新注册/重新注册的 provider（例如关掉再打开 nostr）：只补 ownedLanTcp/BLE
+			// 会让新 provider 永远拿不到 onInbound（见 fount-p2p#38）。
+			await startEnabledProviderListening()
 			signalListenReady = (async () => {
 				if (generation !== gen || !isLive()) return
 				if (!listDiscoveryProviders().length) return

package/pages/index.html

@@ -1,36 +0,0 @@
-<!doctype html>
-<html lang="zh-CN">
-<head>
-	<meta charset="utf-8">
-	<meta name="viewport" content="width=device-width, initial-scale=1">
-	<title>fount 人口统计</title>
-	<style>
-		:root { color-scheme: light dark; }
-		body { font-family: system-ui, sans-serif; max-width: 720px; margin: 3rem auto; padding: 0 1rem; line-height: 1.6; }
-		h1 { font-size: 1.4rem; }
-		.card { border: 1px solid #8884; border-radius: 8px; padding: 1rem 1.25rem; margin: 1rem 0; }
-		.metric { font-size: 2rem; font-weight: 700; }
-		label { display: flex; align-items: center; gap: .5rem; margin: 1rem 0; }
-		#status { opacity: .7; font-size: .9rem; }
-		code { background: #8882; padding: .1em .4em; border-radius: 4px; }
-	</style>
-</head>
-<body>
-	<h1>fount 节点人口统计</h1>
-	<p>基于 Nostr census 事件（kind 30789，<code>t=fount</code> / <code>x=census</code>）的采样估计。监听逻辑由包内 <code>census_monitor</code> 封装：自动监听默认/传入 relay 并经 NIP-66 发现更多，取人口最大的 relay 作为显示源。在线节点数 = <code>Σ(1/p)</code>（Horvitz–Thompson 估计）。</p>
-	<label>
-		<input type="checkbox" id="toggle" checked>
-		人口统计（census）
-	</label>
-	<div class="card">
-		<div>在线节点数估计</div>
-		<div class="metric" id="estimate">0</div>
-		<div id="status">初始化…</div>
-	</div>
-	<div class="card">
-		<div>采样事件数 <span id="sample-size">0</span> · 窗口内事件 <span id="window-events">0</span></div>
-	</div>
-	<footer id="footer" style="opacity:.6;font-size:.85rem">通过 URL 参数 ?relay=wss://... 指定中继；缺省监听默认 relay。</footer>
-	<script type="module" src="./index.mjs"></script>
-</body>
-</html>

package/pages/index.mjs

@@ -1,66 +0,0 @@
-/**
- * fount 人口统计前端（薄壳，逻辑由包内 `census_monitor` 封装）。
- * - `createPopulationMonitor` 自动监听全部默认（或传入）relay、经 NIP-66 发现更多，
- *   并取人口估计最大的 relay 作为显示源，把 `{ estimate, sampleSize, eventsInWindow, relayUrl, relays }`
- *   快照连同 relay 地址传给 onUpdate。
- * - 页面只负责：导入监控器、传显示函数与可选 relay 地址。
- */
-import { createPopulationMonitor } from 'https://esm.sh/@steve02081504/fount-p2p/discovery/nostr/census_monitor.mjs'
-
-const statusEl = document.querySelector('#status')
-const toggleEl = document.querySelector('#toggle')
-
-const params = new URLSearchParams(location.search)
-const relayUrl = params.get('relay')
-
-/** @type {{ stop: () => void } | null} */
-let monitor = null
-
-/**
- * @param {{ estimate: number, sampleSize: number, eventsInWindow: number }} snapshot 快照
- * @returns {void}
- */
-function render(snapshot) {
-	document.querySelector('#estimate').textContent = snapshot.estimate.toLocaleString('zh-CN', { maximumFractionDigits: 1 })
-	document.querySelector('#sample-size').textContent = String(snapshot.sampleSize)
-	document.querySelector('#window-events').textContent = String(snapshot.eventsInWindow)
-}
-
-/** @returns {void} 启动 live 监控（默认/传入 relay 全交给库） */
-function startLive() {
-	if (monitor) return
-	try {
-		monitor = createPopulationMonitor({
-			relays: relayUrl ? [relayUrl] : undefined,
-			/**
-			 * @param {{ estimate: number, sampleSize: number, eventsInWindow: number, relayUrl: string, relays: number }} snapshot 人口快照
-			 * @returns {void}
-			 */
-			onUpdate: snapshot => {
-				render(snapshot)
-				statusEl.textContent = `监听 ${snapshot.relayUrl}（census，共 ${snapshot.relays} 个 relay）`
-			},
-		})
-	}
-	catch (error) {
-		statusEl.textContent = `中继配置无效：${String(error?.message || error)}`
-	}
-}
-
-/** @returns {void} 停止监控 */
-function stopLive() {
-	monitor?.stop()
-	monitor = null
-}
-
-toggleEl.addEventListener('change', () => {
-	if (!toggleEl.checked) {
-		stopLive()
-		render({ estimate: 0, sampleSize: 0, eventsInWindow: 0 })
-		statusEl.textContent = '已关闭'
-		return
-	}
-	startLive()
-})
-
-if (toggleEl.checked) startLive()