@steve02081504/fount-p2p 0.0.46 → 0.0.49

package/AGENTS.md

@@ -24,7 +24,7 @@ Detail docs: [transports](docs/transports.md) · [mesh](docs/mesh.md) · [signal
 | `crypto/crypto.mjs` | Node + browser | `@noble/hashes` + `@noble/curves` only — never `node:crypto` |
 | `crypto/key.mjs` / `crypto/channel.mjs`, disk I/O, LAN/BT, `ws`, CLI / `startNode` | Node (+ Deno bridge) | Do not load the whole package via esm.sh in the browser |
 
-**Browser pages reusing package code:** pages import browser-safe package modules (`core/*`, `crypto/crypto.mjs`, `discovery/nostr/constants|_math|_verify|_monitor`) from esm.sh; their bare `@noble/*` deps resolve via an injected importmap. The frontend static test server (`test/frontend/census_page.test.mjs`) serves the whole package root (offline), injects an importmap into served HTML (`https://esm.sh/@steve02081504/fount-p2p/` → local package root, `@noble/` → `https://esm.sh/@noble/`), and runs the page live against a fake relay (`test/helpers/fake_relay.mjs` with `store`), injecting its `ws://` URL via `?relay=` — no demo mode. Page code stays a thin shell — pass display fn + optional relays; logic lives in the package (`discovery/nostr/census_monitor.mjs`).
+**Browser pages reusing package code:** pages import browser-safe package modules (`core/*`, `crypto/crypto.mjs`, `discovery/nostr/constants|_math|_verify|_monitor`) from esm.sh; their bare `@noble/*` deps resolve via an injected importmap. The frontend static test server (`test/frontend/census_page.test.mjs`) serves the monorepo root (offline) — the page lives in `pages/`, the package in `js/` — injects an importmap into served HTML (`https://esm.sh/@steve02081504/fount-p2p/` → local `js/` package root, `@noble/` → `https://esm.sh/@noble/`), and runs the page live against a fake relay (`test/helpers/fake_relay.mjs` with `store`), injecting its `ws://` URL via `?relay=` — no demo mode. Page code stays a thin shell — pass display fn + optional relays; logic lives in the package (`discovery/nostr/census_monitor.mjs`).
 
 Deno / native / BT: [runtime.md](docs/runtime.md).
 
@@ -47,11 +47,24 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 - `npm run test:live` — live link / LAN smoke
 - `npm run test:fount` — cross-repo Deno bridge (`test/fount/`); see [runtime.md](docs/runtime.md)
 - `npm run test:sim` — tunables co-evolution (dev-only; [sim/AGENTS.md](sim/AGENTS.md))
+- `npm run test:checks` — the three static-health suites below only
+- `npm run check:text_lf:fix` — rewrite line-ending violations (the suites themselves never write)
 - `node scripts/check-imports.mjs` — relative import check
 - `node scripts/find-unused-exports.mjs` — dead-export scan (`--fount <path>` optional)
 - Assertions: `test/helpers/assert.mjs`
 - Fixed-seed identity: `test/helpers/identity.mjs`
 - Mock discovery: `test/helpers/mock_discovery.mjs`
+- Transport fakes must mirror the backend's failure signalling: a fake `RTCPeerConnection` whose `close()` stays silent (no `connectionstatechange`) hides re-entrancy bugs where a replaced connection closes the live one (fount-p2p#39, `link/providers/webrtc.mjs`).
+
+## Static checks (`scripts/checks/`, ported from fount's check standard)
+
+| Check | Enforces |
+| --- | --- |
+| `text_lf` | Every UTF-8 text file (fatal decode, no NUL / C0 control byte; empty files exempt) uses LF, ends with exactly one LF (single-line `.svg` instead ends with none), and does not start with LF (leading UTF-8 BOM skipped). Binary files such as `gradle-wrapper.jar` are skipped. Scanner: `scripts/checks/text_lf.mjs`; `npm run check:text_lf:fix` writes the fix |
+| `jsdoc_no_english` | JSDoc summaries are Chinese (CJK required; a pure-English summary or a missing summary fails); multi-line blocks put a line break right after `/**` and before `*/`. Tag-only blocks (`@param` / `@typedef` …) are fine, empty `/** */` stubs are not. Scanner: `scripts/checks/jsdoc_no_english.mjs` |
+| `agents_md_english` | Every `AGENTS.md` and each `.md` reachable through its local links is English (no CJK) and its links resolve; a non-`AGENTS.md` doc in that closure must live under a `docs/` directory. Scanner: `scripts/checks/agents_md_english.mjs` |
+
+The scanners run from `js/test/pure/*.test.mjs` (repo-wide scope: they walk up to the monorepo root, so `kotlin/AGENTS.md` and the root docs are covered too). Docs language is unified to English — write agent docs and `.md` in the AGENTS.md closure in English.
 
 ## Hard rules
 

package/discovery/nostr/constants.mjs

@@ -57,7 +57,5 @@ export const NOSTR_CENSUS_KIND = 30789
 
 /** census 订阅/发布标签：`t=fount` + `x=census`（subscribeNostrKind 以 rendezvousKey/tagX 匹配）。 */
 export const CENSUS_TAG_FOUNT = 'fount'
-/**
- *
- */
+/** census 标签 `x` 的取值（`t=fount` + `x=census` 共同标识 census 事件）。 */
 export const CENSUS_TAG_X = 'census'

package/discovery/nostr/index.mjs

@@ -203,7 +203,8 @@ async function signNostrEvent(kind, tags, content, secretKey) {
 }
 
 /**
- * 全量发布到给定 relay（任一成功即返回）。
+ * 全量发布到给定 relay：任一成功即返回，其余 relay 的发布留在后台自行结算。
+ * 每个 relay 尝试都有界（连接超时 / OK 超时 / 入队等待上限），故后台不会永久悬挂。
  * @param {string[]} relayUrls 中继 URL 列表
  * @param {object} event 待发布事件
  * @param {AbortSignal} [signal] 取消信号
@@ -212,19 +213,30 @@ async function signNostrEvent(kind, tags, content, secretKey) {
 async function publishEvent(relayUrls, event, signal) {
 	const urls = dedupeRelayUrls(relayUrls)
 	if (!urls.length) throw new Error('nostr: no relay')
-	let published = false
-	let lastError = null
-	await Promise.allSettled(urls.map(async relayUrl => {
+	const targets = (await Promise.all(urls.map(async relayUrl => {
 		try {
-			const connectTarget = await resolveRelayConnectTarget(relayUrl)
-			if (!connectTarget) return
-			if (await publishViaSharedRelay(relayUrl, event, signal, connectTarget)) published = true
+			return { relayUrl, connectTarget: await resolveRelayConnectTarget(relayUrl) }
 		}
-		catch (error) {
-			lastError = error
+		catch {
+			return { relayUrl, connectTarget: null }
 		}
-	}))
-	if (!published) throw lastError || new Error('nostr: no relay accepted publish')
+	}))).filter(target => target.connectTarget)
+	let lastError = null
+	if (!targets.length) throw new Error('nostr: no relay')
+	const attempts = targets.map(target => publishViaSharedRelay(target.relayUrl, event, signal, target.connectTarget)
+		.then(ok => {
+			if (ok) return true
+			lastError = new Error(`nostr: relay rejected publish (${target.relayUrl})`)
+			return false
+		}, error => {
+			lastError = error
+			return false
+		}))
+	// 首个成功的 relay 即结算调用方；其余尝试继续在后台跑（失败已就地吞掉，不会变成 unhandled rejection）。
+	const accepted = await Promise.race(attempts.map((attempt, index) => attempt.then(ok => ok ? index : -1)))
+	if (accepted >= 0) return
+	await Promise.all(attempts)
+	throw lastError || new Error('nostr: no relay accepted publish')
 }
 
 /**

package/discovery/nostr/session.mjs

@@ -16,6 +16,24 @@ const NOSTR_PUBLISH_OK_TIMEOUT_MS = 3_000
 const NOSTR_RECONNECT_DELAY_MS = 500
 /** 无 sub/publish 工作时共享 relay 空闲回收延迟（给连续 send 复用窗口）。 */
 const NOSTR_IDLE_DROP_MS = 2_000
+/**
+ * 已入队 publish 的等待上限（从入队起算，覆盖多次「连不上 → 退避重连」）。
+ * 连接超时 2s + 重连间隔 0.5s ≈ 2.5s/轮，20s 约等于 8 轮；连不上的 relay 必须结算，
+ * 否则请求永久留在 pendingPublishes 里（见 fount-p2p#37）。
+ */
+export const NOSTR_QUEUED_PUBLISH_DEADLINE_MS = 20_000
+
+/** 测试可缩短的入队 publish 等待上限。 */
+let queuedPublishDeadlineMs = NOSTR_QUEUED_PUBLISH_DEADLINE_MS
+
+/**
+ * 覆盖入队 publish 等待上限（测试用；传 null 恢复默认）。
+ * @param {number | null} value 毫秒上限；null 恢复默认
+ * @returns {void}
+ */
+export function setQueuedPublishDeadlineMsForTests(value) {
+	queuedPublishDeadlineMs = value == null ? NOSTR_QUEUED_PUBLISH_DEADLINE_MS : value
+}
 
 /**
  * @param {string[] | undefined | null} urls 原始列表
@@ -216,6 +234,7 @@ function publishEventOnRelay(ws, relayUrl, event, signal, isCurrent) {
  *   attempt: number,
  *   onAbort: (() => void) | null,
  *   removeAbort: (() => void) | null,
+ *   deadline: ReturnType<typeof setTimeout> | null,
  *   resolve: (ok: boolean) => void,
  *   reject: (err: Error) => void,
  * }} NostrPublishRequest
@@ -326,7 +345,7 @@ function attachSharedRelaySocket(relayUrl, session, ws) {
 		if (session.inflightPublishes.length) {
 			session.pendingPublishes.push(...session.inflightPublishes)
 			for (const publishRequest of session.inflightPublishes)
-				attachQueuedAbort(session, publishRequest)
+				attachQueuedAbort(relayUrl, session, publishRequest)
 			session.inflightPublishes = []
 		}
 		if (!hasPendingWork(session)) {
@@ -465,6 +484,8 @@ function flushPendingPublishes(relayUrl, session, socket) {
 		publishRequest.removeAbort?.()
 		publishRequest.onAbort = null
 		publishRequest.removeAbort = null
+		// 请求已进入实际发送：等待上限改由本次 send 的 OK 超时负责。
+		clearQueuedDeadline(publishRequest)
 		const attempt = ++publishRequest.attempt
 		session.inflightPublishes.push(publishRequest)
 		void publishEventOnRelay(socket, relayUrl, publishRequest.event, publishRequest.signal, () => publishRequest.attempt === attempt)
@@ -475,23 +496,83 @@ function flushPendingPublishes(relayUrl, session, socket) {
 	}
 }
 
+/**
+ * 清除待发请求的等待上限定时器。
+ * @param {NostrPublishRequest} publishRequest 待发请求
+ * @returns {void}
+ */
+function clearQueuedDeadline(publishRequest) {
+	if (!publishRequest.deadline) return
+	clearTimeout(publishRequest.deadline)
+	publishRequest.deadline = null
+}
+
+/**
+ * 把一个尚未发出的 publish 移出队列并清掉它的等待上限。
+ * 队列已在别处清空（已 flush 到 socket / 已 abort）时返回 false。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {NostrPublishRequest} publishRequest 待发请求
+ * @returns {boolean} 是否确实已出队
+ */
+function dequeueQueuedPublish(relayUrl, session, publishRequest) {
+	const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
+	if (pendingIndex < 0) return false
+	clearQueuedDeadline(publishRequest)
+	publishRequest.removeAbort?.()
+	publishRequest.onAbort = null
+	publishRequest.removeAbort = null
+	session.pendingPublishes.splice(pendingIndex, 1)
+	// 这条 relay 已无任何工作：立刻回收，别把连不上的 socket / 重连循环留在进程里。
+	if (!hasPendingWork(session)) {
+		sharedRelaySessions.delete(relayUrl)
+		clearSharedRelayReconnect(session)
+		if (session.ws) dropWebSocket(session.ws)
+		session.ws = null
+	}
+	return true
+}
+
+/**
+ * 为队列中的 publish 挂上等待上限：从入队起算，超时即 reject 并出队。
+ * 只覆盖「尚未拿到可用 socket」的阶段；已 flush 到 open socket 的请求由 publishEventOnRelay 的 OK 超时负责。
+ * 定时器跨断线重发保留（请求在 pending ↔ inflight 间移动时不重置），故僵尸请求的总等待有界。
+ * @param {string} relayUrl 中继 URL
+ * @param {SharedRelaySession} session 会话
+ * @param {NostrPublishRequest} publishRequest 待发请求
+ * @returns {void}
+ */
+function attachQueuedDeadline(relayUrl, session, publishRequest) {
+	clearQueuedDeadline(publishRequest)
+	if (queuedPublishDeadlineMs <= 0) return
+	const timer = setTimeout(() => {
+		publishRequest.deadline = null
+		if (!dequeueQueuedPublish(relayUrl, session, publishRequest)) return
+		nodeDebug('p2p:nostr publish deadline', {
+			url: relayUrl,
+			err: `nostr: connect timeout for ${relayUrl}`,
+		})
+		publishRequest.reject(new Error(`nostr: connect timeout for ${relayUrl}`))
+	}, queuedPublishDeadlineMs)
+	timer.unref?.()
+	publishRequest.deadline = timer
+}
+
 /**
  * 为队列中的 publish 挂上 abort 处理：先移除监听器（释放 signal 对回调/event/session 的引用），
  * 再从队列删除并 reject。
+ * @param {string} relayUrl 中继 URL
  * @param {SharedRelaySession} session 会话
  * @param {SharedRelaySession['pendingPublishes'][number]} publishRequest 待发请求
  * @returns {void}
  */
-function attachQueuedAbort(session, publishRequest) {
+function attachQueuedAbort(relayUrl, session, publishRequest) {
 	const { signal, reject } = publishRequest
 	/**
 	 * 处理 abort 事件
 	 */
 	publishRequest.onAbort = () => {
-		publishRequest.removeAbort?.()
-		const pendingIndex = session.pendingPublishes.indexOf(publishRequest)
-		if (pendingIndex < 0) return
-		session.pendingPublishes.splice(pendingIndex, 1)
+		if (!dequeueQueuedPublish(relayUrl, session, publishRequest)) return
 		reject(new Error('nostr: aborted'))
 	}
 	/**
@@ -525,7 +606,8 @@ function settleInflightPublish(relayUrl, session, publishRequest, attempt, settl
 
 /**
  * 通过共享 relay 会话发布 EVENT：复用已打开 socket，避免每次 send 重开一条连接（内存泄漏）。
- * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发。
+ * 无现成连接时入队并触发连接，连上后由 flushPendingPublishes 统一派发；
+ * 连不上的 relay 由入队等待上限（NOSTR_QUEUED_PUBLISH_DEADLINE_MS）reject，不会永久悬挂。
  * @param {string} relayUrl 中继 URL
  * @param {object} event 待发布事件
  * @param {AbortSignal} [signal] 取消信号
@@ -541,13 +623,15 @@ export function publishViaSharedRelay(relayUrl, event, signal, connectTarget) {
 		const session = acquireSharedRelay(relayUrl, connectTarget)
 		clearIdleDrop(session)
 		/** @type {SharedRelaySession['pendingPublishes'][number]} */
-		const publishRequest = { event, signal, attempt: 0, resolve, reject, onAbort: null, removeAbort: null }
-		attachQueuedAbort(session, publishRequest)
+		const publishRequest = { event, signal, attempt: 0, deadline: null, resolve, reject, onAbort: null, removeAbort: null }
+		attachQueuedAbort(relayUrl, session, publishRequest)
 		session.pendingPublishes.push(publishRequest)
-		if (session.ws?.readyState === WebSocket.OPEN)
+		if (session.ws?.readyState === WebSocket.OPEN) {
 			flushPendingPublishes(relayUrl, session, session.ws)
-		else
-			scheduleSharedRelayConnect(relayUrl, session)
+			return
+		}
+		attachQueuedDeadline(relayUrl, session, publishRequest)
+		scheduleSharedRelayConnect(relayUrl, session)
 	})
 }
 

package/docs/signaling.md

@@ -14,9 +14,20 @@ Internal WebRTC (`needsOfferAnswer`) glare and handshake. Shells use the fount-n
 
 Frames: `hello` then `auth`. On simultaneous dial, peer `auth` can arrive before peer `hello` — buffer it (`pendingAuth` in `link/pipe.mjs`); never drop.
 
-## Windows / `trickleIceOff`
+## ICE candidate gathering and the local-hostname ladder
 
-When set: send final offer/answer after ICE gathering, dedupe remote signals, queue remote ICE until both descriptions are ready.
+There is no `trickleIceOff` switch: candidates travel inside the description, because a peer must already hold the remote description before it accepts candidates. Every link therefore gathers locally first and then sends one offer/answer.
+
+`.local` (mDNS) host candidates are usually unresolvable for the peer, so the default policy drops them. When that leaves the local candidate set **empty**, the link cannot work no matter what the peer supports, so the initiator escalates to the next, more permissive policy and rebuilds the peer connection on that rung (`ICE_LOCAL_HOSTNAME_LADDER` in `node/signaling_config.mjs`; `iceLocalHostnameLadder` derives the rungs from the configured start):
+
+1. `drop` — solve the mDNS problem by not offering the candidate.
+2. `none` — offer everything and let the peer decide.
+
+This decision is driven purely by the observed candidate set, never by the platform, so any backend on any host follows the same path. `rewrite-loopback` is not part of the ladder (rewriting a candidate to `127.0.0.1` is only useful same-machine); it stays available as an explicit start and, when set, is used alone.
+
+Each rung is a **fresh link attempt** — new peer connection, new offer, new DTLS fingerprint — not a renegotiation of a live connection, so `pipe` fingerprint-binding semantics are unchanged. The offer carries the rung number; the responder rebuilds on that same rung and echoes it in the answer and never escalates on its own, which keeps convergence bounded. The whole ladder shares the `handshakeTimeoutMs` budget.
+
+Gathering itself is bounded by `collectIceGathering` (`link/providers/webrtc.mjs`): it finishes on `iceGatheringState === 'complete'`, on a quiet candidate stream after candidates arrived (`ICE_CANDIDATE_SETTLE_MS`), or after `ICE_GATHERING_STALL_MS` when nothing was gathered at all — the last case is logged, and DTLS/data-channel timeouts decide instead of a hard 10s failure. `handshakeTimeoutMs` stays the hard stop on every path, including the quiet-window wait. Server-side polyfills (`node-datachannel`) deliver candidates only through `icecandidate` events and `localDescription.sdp` carries no candidate lines, so progress is counted from events rather than by diffing SDP.
 
 ## Runtime channels
 
@@ -29,6 +40,6 @@ Channel → components:
 - `nostr` (nostr discovery + nostr link) — config `relay` **replaces** the default public relay list (do not merge defaults back in).
 - `lan` (lan discovery + lan_tcp link)
 - `bt` (bt discovery + ble_gatt link)
-- `webrtc` (webrtc link data-transport fallback) — config `iceLocalHostnamePolicy` (`none` / `rewrite-loopback` / `drop`, Windows defaults `drop`) and `trickleIceOff` (send final offer/answer after ICE gathering).
+- `webrtc` (webrtc link data-transport fallback) — config `iceLocalHostnamePolicy` is the ladder's **start** (`drop` by default; `none`, or `rewrite-loopback` for same-machine debugging).
 
 To run a node on only a few channels, use the `disableAllChannels` helper: `{ channels: disableAllChannels({ nostr: { relay: [...] } }) }` enables only `nostr` (with its per-channel relay) and disables the rest; use `true` to enable a channel with its default config (`disableAllChannels({ nostr: true, webrtc: true })`).

package/docs/transports.md

@@ -45,10 +45,20 @@ LinkHandle for upper layers: `ready` / `nodeHash` / `send` / `onEnvelope` / `onD
 
 Provider optional hooks (package-internal): `ensureListening`, `localEndpoint`, `canReach`, `caps.probe: 'sync' | 'native'` (`native` = skipped on ensureRuntime fast-listen). Discovery `connectToNode` / `sendNodeSignal` may return `false` when the path is unavailable; fan-out treats that as silent skip. Per-provider throw/false in discovery and link dial fallback are silent; only total failure of the abstraction surfaces to the caller.
 
-Each registry only calls `ensureListening` on **its own** `lan_tcp` / `ble_gatt` instances (unique registry ids like `lan_tcp:ab12cd34`). Never fan out listening to other registries' sockets.
+Each registry only owns its own `lan_tcp` / `ble_gatt` instances (unique registry ids like `lan_tcp:ab12cd34`), so those are listened to per registry. Every other **registered and enabled** provider (e.g. `nostr`, `webrtc`) is listened to by the registry that can see it: `ensureRuntime` and `reloadDiscoveryRelays` call `ensureListening` on any enabled provider that has no registered stop function yet. A provider registered later — notably the fresh instance `reconcileLinkProviders()` installs when a channel is toggled off and back on — must be picked up by that pass, otherwise it silently drops every inbound `link-open` (a missing listener is logged as `p2p:nostr link-open dropped — listener not attached`).
 
 Chain `providerId` on the LinkHandle stays the short name (`lan_tcp` / `ble_gatt` / `webrtc` / `nostr`) for scheduling/stats.
 
+## Bounded waits (no unbounded dial / publish)
+
+Nothing on the dial path may wait forever:
+
+- Intra-relay publish (`discovery/nostr/session.mjs`): a request queued behind a relay that never completes its WebSocket connect is rejected with a connect-stage error after `NOSTR_QUEUED_PUBLISH_DEADLINE_MS`, and the session is reclaimed. The EVent OK timeout only starts once a socket is open, so it cannot cover the connect stage.
+- Relay fan-out (`discovery/nostr/index.mjs` `publishEvent`): resolves as soon as **one** relay accepts; the remaining publishes keep running in the background but are bounded by the above.
+- One `ensureLinkToNode` (`transport/link_registry.mjs`): bounded by `LINK_DIAL_DEADLINE_MS` (larger than the publish deadline, so a dead relay normally fails through the provider's own error path). On timeout the in-flight promise is dropped from `inflights` so later dials start a fresh attempt instead of reusing a stuck one.
+
+`kotlin/` mirrors all three; there a connect coroutine holding `sessionMutex` must also be cancellable (see [kotlin/AGENTS.md](../../kotlin/AGENTS.md)).
+
 ## Level table
 
 | id | level |
@@ -81,6 +91,10 @@ Plain TCP on the LAN. Registry schedules listen in the background after `ensureR
 
 Discovery signal + dual DataChannel; DTLS fingerprint as handshake binding; `needsOfferAnswer` glare path. Soft-fail (`null`) continues to lower-level providers. Backend: `node-datachannel` when the native addon loads, else pure-JS `node-rtc-connection` (Android/Termux skips native). See [runtime.md](runtime.md).
 
+Every link gathers local ICE candidates first and then sends one offer/answer (there is no trickle mode: a peer must already hold the remote description before it accepts candidates). `collectIceGathering` (`link/providers/webrtc.mjs`) therefore does not wait for `iceGatheringState === 'complete'` alone — server-side polyfills leave the state at `gathering` when every relay times out or when the local-hostname policy drops all host candidates. It also finishes on a quiet candidate stream (`ICE_CANDIDATE_SETTLE_MS`) and gives up after `ICE_GATHERING_STALL_MS` when nothing was gathered, so DTLS/data-channel timeouts decide instead of a hard failure. `handshakeTimeoutMs` remains the hard stop on every path. Progress is counted from `icecandidate` events, not SDP diffs, because `localDescription.sdp` carries no candidate lines on those backends.
+
+When the configured local-hostname policy drains every candidate the link cannot work at all, so the initiator escalates through `ICE_LOCAL_HOSTNAME_LADDER` (`drop` → `none`) and rebuilds the peer connection per rung; the responder follows the rung named in the offer. Nothing here is platform-specific. Details: [signaling.md](signaling.md).
+
 ### `ble_gatt` (40)
 
 GATT write/notify; binding = shared `linkId`; needs BT peer hint (`peripheralId` in discovery meta); optional noble/bleno. Per-registry instance like `lan_tcp`; `isAvailable` / `canReach` gate dial. On Win32, scan-only stacks cannot accept inbound BLE links. One BLE adapter cannot host two independent peripherals in-process — production is one node per process. Hardware probe: [runtime.md](runtime.md).

package/index.mjs

@@ -37,6 +37,7 @@ import {
 	unlockReputationMax,
 } from './node/reputation_sync.mjs'
 import { getRoutingProfile, setRoutingProfile } from './node/routing_profile.mjs'
+import { attachNetworkVerification, createNetworkVerificationService, getNetworkVerificationService, proveNetworkVerification } from './node/verification.mjs'
 import { createGroupLinkSet } from './transport/group_link_set.mjs'
 import {
 	configureLinkRegistry,
@@ -62,12 +63,14 @@ import {
  * 包门面：节点、infra、mesh/registry、信誉同步、node-scope 等公开导出。
  */
 export {
+	attachNetworkVerification,
 	attachReputationSyncWire,
 	attachNodeScopeDefaultFeatures,
 	closeNode,
 	configureLinkRegistry,
 	configureNodeStorage,
 	createGroupLinkSet,
+	createNetworkVerificationService,
 	createScopedLinkRoom,
 	ensureChannelAvailable,
 	ensureLinkToNode,
@@ -76,6 +79,7 @@ export {
 	ensureOverlayRouter,
 	ensureUserRoom,
 	getLinkRegistry,
+	getNetworkVerificationService,
 	getNodeDir,
 	getNodeHash,
 	getNodePopulationEstimate,
@@ -93,6 +97,7 @@ export {
 	loadReputation,
 	lockReputationMax,
 	onPeerHealth,
+	proveNetworkVerification,
 	pullReputationFromNode,
 	registerDiscoveryProvider,
 	registerLinkProvider,

package/link/providers/ble_gatt.mjs

@@ -63,7 +63,7 @@ async function openGattPipe(options) {
 }
 
 /**
- * Central dial。
+ * central 角色主动拨号：按 peer hint 扫描外围设备并建立 GATT 链路。
  * @param {object} options dial 选项
  * @returns {Promise<import('./index.mjs').LinkHandle>} 已就绪的 link
  */
@@ -187,7 +187,7 @@ export function createBleGattLinkProvider() {
 			uuid: BLE_DATA_CHAR_UUID,
 			properties: ['write', 'writeWithoutResponse', 'notify'],
 			/**
-			 * stoprocent/bleno onWriteRequest(connection, data, offset, withoutResponse, callback)
+			 * peripheral 角色的写入回调（stoprocent/bleno onWriteRequest 签名）。
 			 * @param {*} _connection 连接句柄
 			 * @param {Buffer} data 写入
 			 * @param {number} _offset 偏移

package/link/providers/index.mjs

@@ -9,7 +9,8 @@
  *   onDown: (callback: (reason: string) => void) => () => void,
  *   close: (reason?: string) => Promise<void>,
  *   stats: () => object,
- * }} LinkHandle */
+ * }} LinkHandle
+ */
 
 /**
  * @typedef {{

package/link/providers/nostr/index.mjs

@@ -5,6 +5,7 @@ import { base64ToBytes, bytesToBase64 } from '../../../core/bytes_codec.mjs'
 import { isHex64 } from '../../../core/hexIds.mjs'
 import { getDiscoveryProvider, sendNodeSignalPacket } from '../../../discovery/index.mjs'
 import { NOSTR_SIGNAL_KIND, resolveNostrRelayUrls } from '../../../discovery/nostr/index.mjs'
+import { nodeDebug, shortHash } from '../../../node/log.mjs'
 import { ms } from '../../../utils/duration.mjs'
 import { createLruMap } from '../../../utils/lru.mjs'
 import { FRAME_HEADER_BYTES, maxFrameChunkBytesForPayload } from '../../frame.mjs'
@@ -12,9 +13,11 @@ import { asLinkHandle } from '../../pipe.mjs'
 import { LINK_LEVEL_NOSTR } from '../levels.mjs'
 import { createLinkIdBoundPipe } from '../link_id_pipe.mjs'
 
-/** 单包 payload（UTF-8 / base64）上限，避免撞 relay content 限制。
- *  默认兜底取 2026-08 本机对默认公共 relay 的 NIP-11 `max_message_length` 非零最小值（131072 = nostr.mom）。
- *  有 relay 信息时用实测非零最小值覆盖（见 refreshPayloadCap），无 relay / 未探测到时用此默认。 */
+/**
+ * 单包 payload（UTF-8 / base64）上限，避免撞 relay content 限制。
+ * 默认兜底取 2026-08 本机对默认公共 relay 的 NIP-11 `max_message_length` 非零最小值（131072 = nostr.mom）。
+ * 有 relay 信息时用实测非零最小值覆盖（见 refreshPayloadCap），无 relay / 未探测到时用此默认。
+ */
 export const MAX_LINK_PAYLOAD_CHARS = 131072
 
 /** relay info（NIP-11）单次探测超时。 */
@@ -52,8 +55,10 @@ export function estimateEventMessageBytes(packet) {
 	}])).length
 }
 
-/** relay cap 低于此字符数视为无法承载最小正 chunk（帧头 + 1 字节 chunk 的完整 EVENT 封装），从统一上限中剔除。
- *  这类 relay 即便能传也无法携带有效载荷（maxFrameChunkBytesForPayload 得 0），参与取最小值只会无谓拖低/毒化整条链路。 */
+/**
+ * relay cap 低于此字符数视为无法承载最小正 chunk（帧头 + 1 字节 chunk 的完整 EVENT 封装），从统一上限中剔除。
+ * 这类 relay 即便能传也无法携带有效载荷（maxFrameChunkBytesForPayload 得 0），参与取最小值只会无谓拖低/毒化整条链路。
+ */
 export const MIN_USABLE_RELAY_CAP_CHARS = estimateEventMessageBytes({
 	type: 'link',
 	op: 'b',
@@ -323,7 +328,15 @@ export function createNostrLinkProvider(options = {}) {
 		const op = String(packet.op || '')
 		if (op === 'open') {
 			if (sessions.has(linkId)) return
-			if (!onInbound || !localIdentity) return
+			if (!onInbound || !localIdentity) {
+				// 监听未挂上（例如通道关掉再打开后 registry 没重新 ensureListening）时入站包会被丢弃；
+				// 静默丢弃曾让「对端明明在线却始终握手超时」无法诊断（见 fount-p2p#38）。
+				nodeDebug('p2p:nostr link-open dropped — listener not attached', {
+					peer: shortHash(from),
+					linkId: shortHash(linkId),
+				})
+				return
+			}
 			await refreshPayloadCap(resolveRelayUrls())
 			if (sessions.has(linkId)) return
 			const pipe = openPipe({