@steve02081504/fount-p2p 0.0.10 → 0.0.12

package/README.md

@@ -24,7 +24,9 @@ await startNode({ nodeDir: '/path/to/p2p/node' })
 await ensureUserRoom()
 ```
 
-Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`, `@steve02081504/fount-p2p/transport/link_registry`, `@steve02081504/fount-p2p/registries/event_type`.
+Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / rooms). Do not import `link/` or choose WebRTC / BLE / LAN yourself.
+
+Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`, `@steve02081504/fount-p2p/transport/link_registry`, `@steve02081504/fount-p2p/transport/signal_crypto`, `@steve02081504/fount-p2p/registries/event_type`.
 
 ## Layout
 
@@ -33,31 +35,47 @@ Subpath exports mirror source directories, e.g. `@steve02081504/fount-p2p/dag`,
 | L0 | `core/` | Pure primitives: `hexIds`, `entity_id*`, `canonical_json` |
 | L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
 | L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
-| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery, RTC links, rooms |
-| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/` | Federation, store-and-forward, DAG, EVFS |
+| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery + fount-network registry/rooms (`link/providers` are package-private) |
+| L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `governance/`, `reputation/` | Federation, store-and-forward, DAG, EVFS, tunables |
 | — | `registries/` | Pluggable registries (event type, part path, room provider, …) |
 
 Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscoveryProvider`, …).
 
-Root contains only the facade and package metadata; all modules live in layered subdirectories. After a layout migration, run `node scripts/cleanup-root-duplicates.mjs` to drop stale root stubs.
+**Transport modules** (exported under `./transport/*`):
+
+| Module | Role |
+|---|---|
+| `link_registry.mjs` | fount-network facade: dial fallback, scope/overlay |
+| `runtime_bootstrap.mjs` | Progressive `ensureRuntime` (register + background listen / discovery / BT) |
+| `offer_answer.mjs` | Discovery-signal glare for offer/answer providers |
+| `signal_crypto.mjs` | Rendezvous topics + AES-GCM signal packets |
+
+`ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
+
+Root contains only the facade and package metadata; all modules live in layered subdirectories.
 
 ## Tests
 
 ```bash
 npm test              # package pure + integration (Node)
 npm run test:fount    # cross-repo bridge (Deno; requires fount on PATH)
-npm run test:live     # RTC / link smoke (requires node-datachannel)
+npm run test:live     # link / LAN / glare smoke
 npm run test:sim      # tunables co-evolution sim (dev only, not published; --social-tunables to write back)
 ```
 
 During development: `node scripts/check-imports.mjs` validates relative imports. After a layout migration, `node scripts/cleanup-root-duplicates.mjs` removes stale root-level stubs.
 
+Maintainer notes for agents / contributors: [AGENTS.md](./AGENTS.md). Sim harness fidelity: [sim/AGENTS.md](./sim/AGENTS.md).
+
 ## Optional dependencies
 
-- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Unavailable when there is no adapter, load fails, or the radio never reaches poweredOn — other discovery/link paths continue.
+- `@stoprocent/noble` / `@stoprocent/bleno` — Bluetooth (optionalDependencies). Hardware probe is subprocess-only; see [docs/runtime.md](./docs/runtime.md).
+- `node-datachannel` — WebRTC DataChannels (dependency).
+- `ws` — Nostr discovery/signaling WebSockets (dependency).
 
 Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStoragePlugin` and injected; see `node/storage_plugins.mjs` for the local reference implementation.
 
 ## Docs
 
-- Signaling and link setup: [`docs/signaling.md`](./docs/signaling.md)
+- Transports and provider fallback: [`docs/transports.md`](./docs/transports.md)
+- Signaling and WebRTC glare: [`docs/signaling.md`](./docs/signaling.md)

package/core/bytes_codec.mjs

@@ -2,23 +2,78 @@
  * Base64 / hex / bytes 互转（无 Node 依赖，浏览器与 Node 共用）。
  */
 
+const HEX = '0123456789abcdef'
+
+/**
+ * @param {number} code UTF-16 码元（期望为 0-9 / a-f / A-F）
+ * @returns {number} 0–15；非法为 -1
+ */
+function hexNibble(code) {
+	if (code >= 48 && code <= 57) return code - 48
+	if (code >= 97 && code <= 102) return code - 87
+	if (code >= 65 && code <= 70) return code - 55
+	return -1
+}
+
 /**
- * @param {Uint8Array} u8 原始字节
- * @returns {string} 标准 Base64 文本
+ * @param {Uint8Array} bytes 原始字节
+ * @returns {string} 小写 hex
+ */
+export function bytesToHex(bytes) {
+	let out = ''
+	for (let index = 0; index < bytes.length; index++) {
+		const byte = bytes[index]
+		out += HEX[byte >> 4] + HEX[byte & 15]
+	}
+	return out
+}
+
+/**
+ * @param {string} hex hex 文本（可含空白；大小写不敏感）
+ * @returns {Uint8Array} 解码后的字节
  */
-export function u8ToB64(u8) {
+export function hexToBytes(hex) {
+	const text = hex.trim().toLowerCase()
+	if (text.length % 2) throw new Error('p2p: hex length must be even')
+	const out = new Uint8Array(text.length / 2)
+	for (let index = 0; index < out.length; index++) {
+		const high = hexNibble(text.charCodeAt(index * 2))
+		const low = hexNibble(text.charCodeAt(index * 2 + 1))
+		if (high < 0 || low < 0) throw new Error('p2p: invalid hex')
+		out[index] = (high << 4) | low
+	}
+	return out
+}
+
+/**
+ * ArrayBuffer / TypedArray / Uint8Array → Uint8Array；`allowString` 时接受文本。
+ * @param {unknown} value 待转换值
+ * @param {{ allowString?: boolean }} [options] `allowString` 时把非字节输入当文本编码
+ * @returns {Uint8Array} 字节视图（可能与输入共享底层 buffer）
+ */
+export function toBytes(value, options = {}) {
+	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)
+	if (options.allowString)
+		return new TextEncoder().encode(typeof value === 'string' ? value : String(value ?? ''))
+	throw new Error('p2p: bytes must be Uint8Array-compatible')
+}
+
+/**
+ * @param {Uint8Array} bytes 原始字节
+ * @returns {string} 标准 Base64
+ */
+export function bytesToBase64(bytes) {
 	let binary = ''
-	for (let index = 0; index < u8.length; index++) binary += String.fromCharCode(u8[index])
+	for (let index = 0; index < bytes.length; index++) binary += String.fromCharCode(bytes[index])
 	return btoa(binary)
 }
 
 /**
- * @param {string} b64 标准 Base64 文本
+ * @param {string} base64 标准 Base64
  * @returns {Uint8Array} 解码后的字节
  */
-export function b64ToU8(b64) {
-	const bin = atob(b64)
-	const out = new Uint8Array(bin.length)
-	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
-	return out
+export function base64ToBytes(base64) {
+	return Uint8Array.from(atob(base64), char => char.charCodeAt(0))
 }

package/core/tcp_port.mjs

@@ -4,7 +4,7 @@
  * @returns {number | null} 有效端口或 null（未提供 / 非法）
  */
 export function normalizeTcpPort(port) {
-	if (port == null || port === '') return null
+	if (!port) return null
 	const value = Number(port)
 	if (!Number.isInteger(value) || value < 1 || value > 65535) return null
 	return value

package/crypto/checkpoint_sign.mjs

@@ -49,9 +49,9 @@ export function isSignedCheckpoint(checkpoint) {
  * @returns {Promise<{ valid: boolean, reason?: string }>} 校验结果；`valid` 为 false 时 `reason` 说明原因
  */
 export async function verifyRemoteCheckpoint(checkpoint) {
-	if (!checkpoint || typeof checkpoint !== 'object')
+	if (!checkpoint)
 		return { valid: false, reason: 'checkpoint missing or not an object' }
-	if (!Array.isArray(checkpoint.eventIdsInEpoch) || checkpoint.eventIdsInEpoch.length === 0)
+	if (!checkpoint.eventIdsInEpoch?.length)
 		return { valid: false, reason: 'eventIdsInEpoch missing or empty' }
 	const root = merkleRoot(checkpoint.eventIdsInEpoch)
 	if (checkpoint.epoch_root_hash !== root)

package/dag/canonicalize_row.mjs

@@ -8,7 +8,7 @@ import { assertHex64, HEX_ID_64, normalizeHex64 } from '../core/hexIds.mjs'
  * @param {string} key 字段名
  */
 function canonicalizeHexField(obj, key) {
-	if (obj[key] == null || obj[key] === '') return
+	if (!obj[key]) return
 	const normalized = normalizeHex64(obj[key])
 	if (!HEX_ID_64.test(normalized))
 		throw new Error(`${key} must be 64 hex characters`)
@@ -27,7 +27,7 @@ export function canonicalizeRowContent(content, hexKeys, entityHashKeys = new Se
 	for (const key of hexKeys)
 		canonicalizeHexField(out, key)
 	for (const key of entityHashKeys) {
-		if (out[key] == null || out[key] === '') continue
+		if (!out[key]) continue
 		const entityHash = String(out[key]).toLowerCase()
 		if (!isEntityHash128(entityHash))
 			throw new Error(`${key} must be 128 hex characters`)
@@ -54,7 +54,7 @@ export function canonicalizeSignedRow(event, options = {}) {
 	const out = options.prepare ? options.prepare({ ...event }) : { ...event }
 	out.id = assertHex64(out.id, 'id')
 	out.sender = assertHex64(out.sender, 'sender')
-	if (Array.isArray(out.prev_event_ids))
+	if (out.prev_event_ids)
 		out.prev_event_ids = out.prev_event_ids.map((id, index) =>
 			assertHex64(id, `prev_event_ids[${index}]`),
 		)

package/dag/index.mjs

@@ -51,8 +51,7 @@ export function computeLocalTipsHash(tipIds) {
  * @returns {string[]} 去重并字典序排序后的父事件 id 数组
  */
 export function sortedPrevEventIds(raw) {
-	if (!Array.isArray(raw)) return []
-	return [...new Set(raw.filter(id => EVENT_ID_HEX.test(String(id))))].sort()
+	return [...new Set((raw || []).filter(id => EVENT_ID_HEX.test(id)))].sort()
 }
 
 /**
@@ -226,7 +225,7 @@ export function topologicalCanonicalOrder(metas) {
 
 	while (ready.size) {
 		const next = ready.pop()
-		if (next == null) break
+		if (!next) break
 		ordered.push(next)
 		for (const childId of children.get(next) || []) {
 			const remaining = (parentCount.get(childId) || 0) - 1

package/discovery/bt/index.mjs

@@ -46,10 +46,10 @@ function serializeAdvertBlob(adverts) {
 function parseAdvertBlob(raw) {
 	try {
 		const parsed = JSON.parse(Buffer.from(raw).toString('utf8'))
-		if (!Array.isArray(parsed?.entries)) return []
+		if (!parsed?.entries?.length) return []
 		return parsed.entries.map(entry => ({
-			topic: String(entry?.topic || ''),
-			bytes: Uint8Array.from(Buffer.from(String(entry?.data || ''), 'base64')),
+			topic: entry.topic || '',
+			bytes: Uint8Array.from(Buffer.from(entry.data || '', 'base64')),
 		})).filter(entry => entry.topic && entry.bytes.byteLength)
 	}
 	catch {
@@ -148,10 +148,10 @@ export function createBluetoothDiscoveryProvider() {
 					const parsed = JSON.parse(Buffer.from(data).toString('utf8'))
 					const topic = String(parsed?.topic || '')
 					const bytes = Uint8Array.from(Buffer.from(String(parsed?.data || ''), 'base64'))
-					if (topic && bytes.byteLength) 
+					if (topic && bytes.byteLength)
 						for (const listener of signalListeners.get(topic) || [])
 							listener(bytes, { provider: 'bt' })
-					
+
 					callback(bleno.Characteristic.RESULT_SUCCESS)
 				}
 				catch {

package/discovery/bt/probe_child.mjs

@@ -0,0 +1,20 @@
+/**
+ * 子进程 BT 可用性探测：load → poweredOn → stop → exit。
+ * 由 `canUseBluetoothRuntime` spawn；勿在父进程直接跑 waitPoweredOn（会拖住事件循环）。
+ */
+import process from 'node:process'
+
+import { loadNoble, waitPoweredOn } from './runtime.mjs'
+
+const timeoutMs = Number(process.env.FOUNT_BT_PROBE_MS || 3000)
+
+try {
+	const noble = await loadNoble()
+	if (!noble?.startScanningAsync) process.exit(2)
+	await waitPoweredOn(noble, timeoutMs)
+	try { noble.stop() } catch { /* Windows 上 stop 偶发崩；子进程反正要退出 */ }
+	process.exit(0)
+}
+catch {
+	process.exit(1)
+}

package/discovery/bt/runtime.mjs

@@ -1,5 +1,8 @@
+import { spawn } from 'node:child_process'
 import { existsSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import process from 'node:process'
+import { fileURLToPath } from 'node:url'
 
 /**
  * 解析 Bluetooth 角色（scan / dual）。
@@ -31,10 +34,55 @@ export function probeBluetoothHardware() {
 
 /** @type {boolean | null} canUseBluetoothRuntime 缓存 */
 let cachedRuntimeOk = null
+/** @type {Promise<boolean> | null} 并发 canUse 合并为一次子进程探测 */
+let probeInflight = null
+
+const PROBE_CHILD = join(dirname(fileURLToPath(import.meta.url)), 'probe_child.mjs')
+
+/**
+ * 在子进程中探测 BT（父进程 waitPoweredOn 会拖住事件循环；stop() 还可能 AV）。
+ * @param {number} timeoutMs waitPoweredOn 超时
+ * @returns {Promise<boolean>} 子进程 exit 0 为可用
+ */
+function probeBluetoothInSubprocess(timeoutMs) {
+	return new Promise(resolve => {
+		const child = spawn(process.execPath, [PROBE_CHILD], {
+			stdio: 'ignore',
+			env: {
+				...process.env,
+				FOUNT_BT_PROBE_MS: String(timeoutMs),
+			},
+			windowsHide: true,
+		})
+		// 探测是旁路缓存填充；勿拖住父进程事件循环 / shutdown 退出。
+		child.unref()
+		let settled = false
+		/**
+		 * @param {boolean} ok 探测结果
+		 * @returns {void}
+		 */
+		const finish = ok => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			resolve(ok)
+		}
+		const timer = setTimeout(() => {
+			child.kill('SIGKILL')
+			finish(false)
+		}, timeoutMs + 5_000)
+		timer.unref()
+		child.once('error', () => finish(false))
+		child.once('exit', (code, signal) => {
+			if (signal) finish(false)
+			else finish(code === 0)
+		})
+	})
+}
 
 /**
- * 探测 BT 栈是否真正可用（有适配器迹象 → 能 load → poweredOn）。
- * 任一步失败返回 false，调用方回落其它 discovery/link；不抛错。
+ * 探测 BT 栈是否真正可用（硬件迹象 → 子进程 load → poweredOn）。
+ * 任一步失败返回 false；不抛错。
  * @param {number} [timeoutMs=3000] waitPoweredOn 超时
  * @returns {Promise<boolean>} 可用为 true
  */
@@ -44,19 +92,15 @@ export async function canUseBluetoothRuntime(timeoutMs = 3000) {
 		cachedRuntimeOk = false
 		return false
 	}
-	try {
-		const noble = await loadNoble()
-		if (!noble.startScanningAsync) {
-			cachedRuntimeOk = false
-			return false
-		}
-		await waitPoweredOn(noble, timeoutMs)
-		cachedRuntimeOk = true
-	}
-	catch {
-		cachedRuntimeOk = false
-	}
-	return cachedRuntimeOk
+	if (!probeInflight)
+		probeInflight = probeBluetoothInSubprocess(timeoutMs)
+			.then(ok => {
+				cachedRuntimeOk = ok
+				return ok
+			})
+			.finally(() => { probeInflight = null })
+
+	return probeInflight
 }
 
 /**

package/discovery/index.mjs

@@ -23,6 +23,14 @@ export function unregisterDiscoveryProvider(id) {
 	providers.delete(String(id))
 }
 
+/**
+ * 清空全部 discovery provider。
+ * @returns {void}
+ */
+export function clearDiscoveryProviders() {
+	providers.clear()
+}
+
 /**
  * 列出已注册的 discovery provider（按 priority 排序）。
  * @returns {DiscoveryProvider[]} 提供者列表
@@ -32,29 +40,40 @@ export function listDiscoveryProviders() {
 }
 
 /**
- * 通过所有可用 provider 广播 topic advert。
- * 单路失败静默（正常降级）；其它 provider 仍可成功。
- * @param {string} topic advert 主题
- * @param {Uint8Array} bytes advert 载荷
+ * 并行启动各 provider 的 async 钩子；单路失败静默。
+ * @param {DiscoveryProvider[]} list 提供者列表
+ * @param {(provider: DiscoveryProvider) => Promise<(() => void) | null | undefined>} run 单路启动
  * @returns {Promise<() => void>} 统一取消函数
  */
-export async function advertiseTopic(topic, bytes) {
-	const cleanups = []
-	for (const provider of listDiscoveryProviders()) {
-		if (!provider.caps?.canDiscover || typeof provider.advertise !== 'function') continue
-		let cleanup = null
+async function startProvidersParallel(list, run) {
+	const settled = await Promise.all(list.map(async provider => {
 		try {
-			cleanup = await provider.advertise(topic, bytes)
+			const cleanup = await run(provider)
+			return typeof cleanup === 'function' ? cleanup : null
 		}
-		catch { continue }
-		if (typeof cleanup === 'function') cleanups.push(cleanup)
-	}
+		catch {
+			return null
+		}
+	}))
+	const cleanups = settled.filter(Boolean)
 	return () => {
 		for (const cleanup of cleanups)
 			try { cleanup() } catch { /* ignore */ }
 	}
 }
 
+/**
+ * 通过所有可用 provider 广播 topic advert。
+ * 单路失败静默（正常降级）；其它 provider 仍可成功。
+ * @param {string} topic advert 主题
+ * @param {Uint8Array} bytes advert 载荷
+ * @returns {Promise<() => void>} 统一取消函数
+ */
+export async function advertiseTopic(topic, bytes) {
+	const list = listDiscoveryProviders().filter(provider => provider.caps?.canDiscover && typeof provider.advertise === 'function')
+	return startProvidersParallel(list, provider => provider.advertise(topic, bytes))
+}
+
 /**
  * 通过所有可用 provider 订阅 topic advert。
  * 单路失败静默（正常降级）。
@@ -63,20 +82,8 @@ export async function advertiseTopic(topic, bytes) {
  * @returns {Promise<() => void>} 统一取消函数
  */
 export async function subscribeTopic(topic, onAdvert) {
-	const cleanups = []
-	for (const provider of listDiscoveryProviders()) {
-		if (!provider.caps?.canDiscover || typeof provider.subscribe !== 'function') continue
-		let cleanup = null
-		try {
-			cleanup = await provider.subscribe(topic, onAdvert)
-		}
-		catch { continue }
-		if (typeof cleanup === 'function') cleanups.push(cleanup)
-	}
-	return () => {
-		for (const cleanup of cleanups)
-			try { cleanup() } catch { /* ignore */ }
-	}
+	const list = listDiscoveryProviders().filter(provider => provider.caps?.canDiscover && typeof provider.subscribe === 'function')
+	return startProvidersParallel(list, provider => provider.subscribe(topic, onAdvert))
 }
 
 /**
@@ -93,13 +100,15 @@ export async function sendSignal(topic, to, bytes) {
 	if (!capable.length) throw new Error('p2p: no discovery provider can signal')
 	let sent = false
 	let lastError = null
-	for (const provider of capable) try {
-		if (await Promise.resolve(provider.sendSignal(topic, to, bytes)) !== false)
-			sent = true
-	}
-	catch (error) {
-		lastError = error
-	}
+	await Promise.all(capable.map(async provider => {
+		try {
+			if (await Promise.resolve(provider.sendSignal(topic, to, bytes)) !== false)
+				sent = true
+		}
+		catch (error) {
+			lastError = error
+		}
+	}))
 	if (!sent) throw lastError || new Error('p2p: no discovery provider delivered signal')
 }
 
@@ -111,18 +120,6 @@ export async function sendSignal(topic, to, bytes) {
  * @returns {Promise<() => void>} 统一取消函数
  */
 export async function listenSignals(topic, onSignal) {
-	const cleanups = []
-	for (const provider of listDiscoveryProviders()) {
-		if (!provider.caps?.canSignal || typeof provider.onSignal !== 'function') continue
-		let cleanup = null
-		try {
-			cleanup = await provider.onSignal(topic, onSignal)
-		}
-		catch { continue }
-		if (typeof cleanup === 'function') cleanups.push(cleanup)
-	}
-	return () => {
-		for (const cleanup of cleanups)
-			try { cleanup() } catch { /* ignore */ }
-	}
+	const list = listDiscoveryProviders().filter(provider => provider.caps?.canSignal && typeof provider.onSignal === 'function')
+	return startProvidersParallel(list, provider => provider.onSignal(topic, onSignal))
 }