@steve02081504/fount-p2p 0.0.43 → 0.0.46

package/AGENTS.md

@@ -3,7 +3,7 @@
 ## Package layers (`@steve02081504/fount-p2p`)
 
 | Layer | Directory | Role |
-|---|---|---|
+| --- | --- | --- |
 | L0 | `core/` | IDs, logical entity, canonical JSON, bytes |
 | L1 | `crypto/`, `wire/`, `schemas/` | Crypto, wire ingress, canonical validation |
 | L2 | `node/` | `initNode`, identity, entity store, denylist, reputation, storage plugins |
@@ -19,7 +19,7 @@ Detail docs: [transports](docs/transports.md) · [mesh](docs/mesh.md) · [signal
 ### Runtime: isomorphic vs Node
 
 | Surface | Runtime | Notes |
-|---|---|---|
+| --- | --- | --- |
 | `core/*` | Node + browser | No `node:*` builtins |
 | `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 |
@@ -31,6 +31,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 ## Conventions
 
 - Prefer shared helpers under `utils/`, `core/`, `wire/subscribe`, `wire/adapter` — do not reimplement LRU/TTL/inflight/atomic-fs/shuffle.
+- **JSONL read-modify-write:** do it inside `withAsyncMutex(jsonlMutexKey(path))`. `rewriteJsonlKeeping` / `appendJsonlSynced` / `writeJsonlSynced` take that per-file mutex themselves and are **not reentrant** — never call them while already holding the same key (use lock-free `writeJsonl` / `writeJsonlLines` instead). Rewrites preserve the original raw line (a `sanitize` passed to `rewriteJsonlKeeping` / `readJsonlEntries` only affects the value handed to the predicate) and skip the rename when nothing is dropped.
 - **No pure-forward aliases:** do not add `fooText`/`fooAlias` that only `return foo(sameArgs)` when the callee already accepts those types (e.g. never wrap `sha256Hex` as `sha256TextHex`). Domain names must add logic or type narrowing, not just rename.
 - **Heterogeneous backends:** normalize at the load boundary (e.g. `link/rtc/ice_local_hostname.mjs` wraps W3C RTC backends); call sites speak one contract.
 - **File naming:** parent directory is scope — short child names. Tunables default `<dir>/tunables.json` (exception: `schemas/part_query.tunables.json`). Subpath `package.json` exports mirror filenames.
@@ -66,6 +67,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 ### Node / network
 
 - **Node data:** `initNode({ nodeDir, entityStore? })` — `node.json`, `network.json`, `denylist.json`, `reputation.json`, `mailbox/`, `chunks/`. Default EntityStore: `{nodeDir}/entities/`. No `FOUNT_*` env knobs — subprocess IPC uses argv.
+- **Storage vs runtime:** local identity (`ensureNodeSeed` / `getNodeHash` / `resolveLocalEntityHashFromRecoveryPubKeyHex`, all `node/storage` JSON helpers) must not require `initNode`. Configure the dir with `configureNodeStorage({ nodeDir })` (idempotent; cannot switch while running — `closeNode()` first) and only call `initNode` when the network should run. Hosts configure storage unconditionally so entities have a local identity with P2P disabled. [runtime.md](docs/runtime.md)
 - **fount network:** shells use `startNode` / `ensureLinkToNode` / `sendToNodeLink` / rooms — never import `link/` internals or pick a transport. Providers: `registerLinkProvider` from `./link` or facade.
 - **Link `level` vs discovery `priority`:** descending `level` picks data transport (`nostr` = −∞ last resort); ascending `priority` orders handshake/presence media only. [transports.md](docs/transports.md)
 - **Mesh first / no versioning:** ≥N links (K acquaintances + N−K explore); discovery API is `listVisibleNodeHashes` + `connectToNode` only; no topic on the fount-network surface; no version/compat fields. [mesh.md](docs/mesh.md)
@@ -75,7 +77,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 ## Tunables JSON
 
 | File | Directory |
-|---|---|
+| --- | --- |
 | `tunables.json` | `transport/`, `infra/`, `reputation/`, `trust_graph/`, `mailbox/`, `governance/`, `dag/` |
 | `part_query.tunables.json` | `schemas/` |
 

package/dag/storage.mjs

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer'
 import { createReadStream, createWriteStream } from 'node:fs'
-import { appendFile, mkdir, open, readFile, writeFile } from 'node:fs/promises'
-import { dirname } from 'node:path'
+import { appendFile, mkdir, open, unlink, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
 import { createInterface } from 'node:readline'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
@@ -29,26 +29,52 @@ function parseJsonlLine(line, sanitize) {
 }
 
 /**
- * 读取 JSONL 文件并解析为对象数组；缺失或读失败时返回空数组。
+ * 逐行读取 JSONL 原始行（不解析、不净化）。文件缺失（ENOENT）视为空流，
+ * 兼容 cleanup 竞态：群目录被删后台仍在尾巴上读它；其他读错误抛出。
+ * @param {string} filePath 文件路径
+ * @returns {AsyncGenerator<string>} 原始行（readline 已去掉行尾换行）
+ */
+async function* readJsonlRawLines(filePath) {
+	const input = createReadStream(filePath, { encoding: 'utf8' })
+	// stream 内部异步 open 失败会触发 'error' 事件；提前订阅避免 unhandled error，
+	// 真实错误仍由下方 for-await 抛出，由本函数统一收口。
+	input.on('error', () => { })
+	const lines = createInterface({ input, crlfDelay: Infinity })
+	try {
+		for await (const line of lines) yield line
+	}
+	catch (error) {
+		if (error?.code !== 'ENOENT') throw error
+	}
+}
+
+/**
+ * 读取 JSONL 为 `{ row, raw }` 列表，保留原始行以便无损写回。
+ * 空行/解析失败/净化抛错的行跳过；文件缺失（ENOENT）返回空数组，其他读错误抛出。
+ * @param {string} filePath 文件路径
+ * @param {{ sanitize?: (row: object) => object }} [options] 行净化
+ * @returns {Promise<Array<{ row: object, raw: string }>>} 行条目列表
+ */
+export async function readJsonlEntries(filePath, options = {}) {
+	const sanitize = options.sanitize ?? (row => row)
+	/** @type {Array<{ row: object, raw: string }>} */
+	const entries = []
+	for await (const raw of readJsonlRawLines(filePath)) {
+		const row = parseJsonlLine(raw, sanitize)
+		if (row != null) entries.push({ row, raw })
+	}
+	return entries
+}
+
+/**
+ * 读取 JSONL 文件并解析为对象数组；缺失（ENOENT）返回空数组，其他读错误抛出。
  * @param {string} filePath 文件系统路径
  * @param {{ sanitize?: (row: object) => object }} [options] 可选净化函数
  * @returns {Promise<object[]>} 各行解析后的对象列表
  */
 export async function readJsonl(filePath, options = {}) {
-	try {
-		const text = await readFile(filePath, 'utf8')
-		const sanitize = options.sanitize ?? (row => row)
-		/** @type {object[]} */
-		const rows = []
-		for (const line of text.split('\n')) {
-			const row = parseJsonlLine(line, sanitize)
-			if (row) rows.push(row)
-		}
-		return rows
-	}
-	catch {
-		return []
-	}
+	const entries = await readJsonlEntries(filePath, options)
+	return entries.map(entry => entry.row).filter(Boolean)
 }
 
 /**
@@ -60,69 +86,93 @@ export async function readJsonl(filePath, options = {}) {
  */
 export async function* readJsonlStream(filePath, options = {}) {
 	const sanitize = options.sanitize ?? (row => row)
-	const input = createReadStream(filePath, { encoding: 'utf8' })
-	// stream 内部异步 open 失败会触发 'error' 事件；提前订阅避免 unhandled error，
-	// 真实错误仍由下方 for-await 抛出，被外层 try/catch 收口。
-	input.on('error', () => { })
-	const lines = createInterface({ input, crlfDelay: Infinity })
-	try {
-		for await (const line of lines) {
-			const row = parseJsonlLine(line, sanitize)
-			if (row) yield row
-		}
-	}
-	catch (error) {
-		if (error?.code !== 'ENOENT') throw error
+	for await (const line of readJsonlRawLines(filePath)) {
+		const row = parseJsonlLine(line, sanitize)
+		if (row) yield row
 	}
 }
 
 /**
- * 流式过滤重写 JSONL：保留 `keep(row)===true` 的行。
+ * 流式过滤重写 JSONL：保留 `keep(row)===true` 的行，写回的是原始行字节，
+ * `sanitize` 只影响传给 `keep` 的值。
+ *
+ * 在 `jsonlMutexKey(filePath)` 互斥锁内执行；调用方不得已持有同一文件的锁（不可重入）。
  * @param {string} filePath 目标路径
- * @param {(row: object) => boolean} keep 保留谓词
+ * @param {(row: object) => boolean | Promise<boolean>} keep 保留谓词（可异步）
  * @param {{ sanitize?: (row: object) => object }} [options] 读行净化
  * @returns {Promise<{ kept: number, dropped: number }>} 统计
  */
 export async function rewriteJsonlKeeping(filePath, keep, options = {}) {
-	const dir = dirname(filePath)
-	await mkdir(dir, { recursive: true })
+	return withAsyncMutex(jsonlMutexKey(filePath), () => rewriteJsonlKeepingUnlocked(filePath, keep, options))
+}
+
+/**
+ * `rewriteJsonlKeeping` 的无锁实现，调用方须已持有该文件互斥锁。
+ * @param {string} filePath 目标路径
+ * @param {(row: object) => boolean | Promise<boolean>} keep 保留谓词（可异步）
+ * @param {{ sanitize?: (row: object) => object }} [options] 读行净化
+ * @returns {Promise<{ kept: number, dropped: number }>} 统计
+ */
+async function rewriteJsonlKeepingUnlocked(filePath, keep, options = {}) {
+	const sanitize = options.sanitize ?? (row => row)
 	const temporaryPath = atomicTemporaryPath(filePath)
-	/** @type {object[]} */
+	let tempCreated = false
+	/** @type {string[]} */
 	const buffer = []
 	let kept = 0
 	let dropped = 0
-	/** @returns {Promise<void>} */
+	/** @returns {Promise<void>} 将缓冲区原始行写入临时文件 */
 	const flush = async () => {
 		if (!buffer.length) return
-		let block = ''
-		for (const row of buffer)
-			block += `${JSON.stringify(row)}\n`
+		const block = buffer.map(line => `${line}\n`).join('')
 		await appendFile(temporaryPath, block, 'utf8')
+		tempCreated = true
 		buffer.length = 0
 	}
 	try {
-		for await (const row of readJsonlStream(filePath, options))
-			if (keep(row)) {
-				buffer.push(row)
+		for await (const raw of readJsonlRawLines(filePath)) {
+			if (!raw.trim()) continue
+			const row = parseJsonlLine(raw, sanitize)
+			if (row == null) {
+				dropped++
+				continue
+			}
+			if (await keep(row)) {
+				buffer.push(raw)
 				kept++
-				if (buffer.length >= WRITE_JSONL_CHUNK_LINES)
-					await flush()
+				if (buffer.length >= WRITE_JSONL_CHUNK_LINES) await flush()
 			}
 			else dropped++
+		}
 		await flush()
-	}
-	catch { /* source missing */ }
-	if (kept > 0 || dropped > 0)
+		if (dropped === 0) {
+			if (tempCreated) await unlink(temporaryPath).catch(() => { })
+			return { kept, dropped }
+		}
+		await mkdir(dirname(filePath), { recursive: true })
+		if (!tempCreated) {
+			await writeFile(temporaryPath, '', 'utf8')
+			tempCreated = true
+		}
+		const fileHandle = await open(temporaryPath, 'r+')
+		try {
+			await fileHandle.sync()
+		}
+		finally {
+			await fileHandle.close()
+		}
 		await finalizeAtomicRename(temporaryPath, filePath)
-	else
-		try { await writeFile(filePath, '', 'utf8') }
-		catch { /* ok */ }
-
-	return { kept, dropped }
+		return { kept, dropped }
+	}
+	catch (error) {
+		if (tempCreated) await unlink(temporaryPath).catch(() => { })
+		throw error
+	}
 }
 
 /**
- * 读取 JSONL 末行事件的 `id`（DAG tip）；空文件为 null。
+ * 读取 JSONL 末条可解析事件的 `id`（DAG tip）；从文件尾部最多读 1 MiB，
+ * 跳过撕裂/坏行后取最后一个非空且 `id` 非 null 的行；空文件或缺失为 null。
  * @param {string} filePath 文件路径
  * @returns {Promise<string | null>} tip event id
  */
@@ -132,14 +182,20 @@ export async function readJsonlTipId(filePath) {
 		try {
 			const { size } = await fh.stat()
 			if (!size) return null
-			const chunk = Math.min(size, 65_536)
+			const chunk = Math.min(size, 1_048_576)
 			const buffer = Buffer.alloc(chunk)
 			await fh.read(buffer, 0, chunk, size - chunk)
-			const lines = buffer.toString('utf8').split('\n').filter(Boolean)
-			const last = lines[lines.length - 1]
-			if (!last) return null
-			const row = JSON.parse(last)
-			return row?.id != null ? String(row.id) : null
+			const lines = buffer.toString('utf8').split('\n')
+			for (let index = lines.length - 1; index >= 0; index--) {
+				const line = lines[index].trim()
+				if (!line) continue
+				try {
+					const row = JSON.parse(line)
+					if (row && typeof row === 'object' && row.id != null) return String(row.id)
+				}
+				catch { /* 撕裂/坏行：继续向前找 */ }
+			}
+			return null
 		}
 		finally {
 			await fh.close()
@@ -151,30 +207,50 @@ export async function readJsonlTipId(filePath) {
 }
 
 /**
- * 流式重写 JSONL（临时文件 + rename），避免大数组 join 的内存峰值。
+ * 流式写入原始 JSONL 行（临时文件 + fsync + rename），每行自动补 `\n`。
+ * 不取锁——调用方需自行持有 `jsonlMutexKey(filePath)`。
  * @param {string} filePath 目标路径
- * @param {object[]} records 行对象列表
+ * @param {Iterable<string>} lines 原始行（不含换行）
  * @returns {Promise<void>}
  */
-export async function writeJsonl(filePath, records) {
+export async function writeJsonlLines(filePath, lines) {
 	const dir = dirname(filePath)
 	await mkdir(dir, { recursive: true })
 	const temporaryPath = atomicTemporaryPath(filePath)
-	/** @returns {Generator<string>} JSONL 行 */
-	function* lines() {
-		for (const rec of records)
-			yield `${JSON.stringify(rec)}\n`
+	/** @returns {Generator<string>} 带换行的行 */
+	function* withEol() {
+		for (const line of lines)
+			yield `${line}\n`
+	}
+	await pipeline(Readable.from(withEol()), createWriteStream(temporaryPath, { encoding: 'utf8' }))
+	const fileHandle = await open(temporaryPath, 'r+')
+	try {
+		await fileHandle.sync()
+	}
+	finally {
+		await fileHandle.close()
 	}
-	await pipeline(Readable.from(lines()), createWriteStream(temporaryPath, { encoding: 'utf8' }))
 	await finalizeAtomicRename(temporaryPath, filePath)
 }
 
+/**
+ * 流式重写 JSONL（临时文件 + fsync + rename），避免大数组 join 的内存峰值。
+ * 不取锁——`mailbox/store.mjs` 等调用方在自己的 `jsonlMutexKey` 锁内调用；
+ * 需要锁时用 `writeJsonlSynced`。
+ * @param {string} filePath 目标路径
+ * @param {object[]} records 行对象列表
+ * @returns {Promise<void>}
+ */
+export async function writeJsonl(filePath, records) {
+	return writeJsonlLines(filePath, records.map(record => JSON.stringify(record)))
+}
+
 /**
  * @param {string} filePath JSONL 路径
- * @returns {string} 进程内互斥键
+ * @returns {string} 进程内互斥键（路径已规范化为绝对路径）
  */
 export function jsonlMutexKey(filePath) {
-	return `jsonl:${filePath}`
+	return `jsonl:${resolve(filePath)}`
 }
 
 /**
@@ -188,21 +264,23 @@ export async function writeJsonlSynced(filePath, records) {
 }
 
 /**
- * 追加一行 JSONL 并 `fsync`。
+ * 追加一行 JSONL 并 `fsync`；与 rewrite 共用同一 per-file 互斥锁。
  * @param {string} filePath 目标路径
  * @param {object} record 记录对象
  * @returns {Promise<void>}
  */
 export async function appendJsonlSynced(filePath, record) {
-	await mkdir(dirname(filePath), { recursive: true })
-	const fh = await open(filePath, 'a')
-	try {
-		await fh.appendFile(`${JSON.stringify(record)}\n`, 'utf8')
-		await fh.sync()
-	}
-	finally {
-		await fh.close()
-	}
+	return withAsyncMutex(jsonlMutexKey(filePath), async () => {
+		await mkdir(dirname(filePath), { recursive: true })
+		const fh = await open(filePath, 'a')
+		try {
+			await fh.appendFile(`${JSON.stringify(record)}\n`, 'utf8')
+			await fh.sync()
+		}
+		finally {
+			await fh.close()
+		}
+	})
 }
 
 /**

package/discovery/nostr/census.mjs

@@ -21,17 +21,17 @@ import { ensureNodeSeed, getNodeHash } from '../../node/identity.mjs'
 import { getP2PFeatures, isNodeInitialized } from '../../node/instance.mjs'
 import { nodeDebug } from '../../node/log.mjs'
 
-import {
-	CENSUS_TAG_FOUNT,
-	CENSUS_TAG_X,
-	NOSTR_CENSUS_KIND,
-} from './constants.mjs'
 import {
 	CENSUS_TARGET_EVENTS,
 	estimatePopulation,
 	nextInclusionProbability,
 } from './census_math.mjs'
 import { CENSUS_TTL_MS, buildCensusMessage, verifyCensusBytes } from './census_verify.mjs'
+import {
+	CENSUS_TAG_FOUNT,
+	CENSUS_TAG_X,
+	NOSTR_CENSUS_KIND,
+} from './constants.mjs'
 import { resolveRelayConnectTarget } from './relays.mjs'
 
 /** census 订阅标签数组（发布用）。 */

package/discovery/nostr/census_monitor.mjs

@@ -10,6 +10,8 @@
  */
 import { base64ToBytes } from '../../core/bytes_codec.mjs'
 
+import { estimatePopulation } from './census_math.mjs'
+import { CENSUS_TTL_MS, verifyCensusBytes } from './census_verify.mjs'
 import {
 	CENSUS_TAG_FOUNT,
 	CENSUS_TAG_X,
@@ -17,8 +19,6 @@ import {
 	NIP66_BOOTSTRAP_RELAYS,
 	NOSTR_CENSUS_KIND,
 } from './constants.mjs'
-import { estimatePopulation } from './census_math.mjs'
-import { CENSUS_TTL_MS, verifyCensusBytes } from './census_verify.mjs'
 
 /** NIP-66 relay 注册 kind。 */
 const NIP66_KIND = 30166

package/discovery/nostr/constants.mjs

@@ -57,4 +57,7 @@ export const NOSTR_CENSUS_KIND = 30789
 
 /** census 订阅/发布标签：`t=fount` + `x=census`（subscribeNostrKind 以 rendezvousKey/tagX 匹配）。 */
 export const CENSUS_TAG_FOUNT = 'fount'
+/**
+ *
+ */
 export const CENSUS_TAG_X = 'census'

package/discovery/nostr/index.mjs

@@ -18,8 +18,8 @@ import {
 } from '../internal/signal_crypto.mjs'
 import { noteDiscoveryPeerClue } from '../peer_clue.mjs'
 
-import { DEFAULT_RELAY_URLS } from './constants.mjs'
 import { createNostrCensus } from './census.mjs'
+import { DEFAULT_RELAY_URLS } from './constants.mjs'
 import {
 	getListenRelays,
 	getPeerRoute,

package/docs/nostr_relay_discovery.md

@@ -3,6 +3,7 @@
 Nostr is the fount-network fallback transport (`link` level −∞, discovery `priority` 100). This document covers the **relay pool**, NIP-66 discovery, health scoring, advert relay-field signing, and handshake routing. Top-level surface: [signaling.md](signaling.md) · [transports.md](transports.md) · [mesh.md](mesh.md).
 
 Source layout (`discovery/nostr/`):
+
 - `index.mjs` — provider (presence / signal / advert subscriptions)
 - `relays.mjs` — pool, health, NIP-66 discovery, normalization, persistence
 - `selection.mjs` — handshake routing, backoff, fanout
@@ -72,6 +73,7 @@ Lower is better. `recordProbeSuccess` / `recordProbeFailure` / `recordPublishRes
 ## Handshake routing (`selection.mjs`)
 
 `handshakeTargets(nodeHash, attempt)`:
+
 - **Round 0**: peer-claimed `listenRelays` top 4 by composite score (own health + peer rtt); else local `workingRelays` top 4; else pinned top 4.
 - **Round ≥1**: backoff `min(2000 · 2^(attempt−1), 60000)`; base on `lastGoodNostrRelays` (expanded via `expandFromHistory` ≤ 16), or weighted-random sample of `workingRelays` (weight `1/score`); round-0 core always included; fanout capped at `MAX_ROUTING_FANOUT` (64).
 - Retries ≤ `MAX_ROUTING_ATTEMPTS` (4).

package/docs/runtime.md

@@ -2,6 +2,24 @@
 
 `ensureRuntime`, startup/shutdown budgets, and Bluetooth hardware probe. Day-to-day shell rules: [AGENTS.md](../AGENTS.md). Providers: [transports.md](transports.md). Mesh N/K: [mesh.md](mesh.md).
 
+## Offline local identity (storage without a running node)
+
+Three independent stages — do not couple them:
+
+1. **Storage** — `configureNodeStorage({ nodeDir })` records where `node.json` / identity seed live. No runtime, no disk I/O, no discovery.
+2. **Local identity** — `ensureNodeSeed` / `getNodeHash` / `resolveLocalEntityHashFromRecoveryPubKeyHex` (and `node/storage` JSON helpers) only need stage 1, so a local `entityHash` can be created while federation is off.
+3. **Network** — `initNode({ nodeDir, entityStore })` builds the runtime and link graph. Same `nodeDir` as stage 1 reuses the persisted seed and hashes.
+
+```javascript
+import { configureNodeStorage } from '@steve02081504/fount-p2p/node/instance'
+import { resolveLocalEntityHashFromRecoveryPubKeyHex } from '@steve02081504/fount-p2p/node/identity'
+
+configureNodeStorage({ nodeDir: '/data/p2p/node' })
+const entityHash = resolveLocalEntityHashFromRecoveryPubKeyHex(recoveryPubKeyHex) // works with P2P disabled
+```
+
+`configureNodeStorage` is idempotent for the same dir; switching dirs while a node is running is rejected (call `closeNode()` first). `closeNode()` clears the storage config, so re-configure after closing. Consumer hosts (fount, subfount) call `configureNodeStorage` unconditionally at startup and only call `initNode` when P2P is enabled.
+
 ## `ensureRuntime` contract
 
 Returns after registering lan / nostr discovery providers (subject to the signaling `channels` whitelist), registering all enabled link providers (including `ble_gatt`), and scheduling background warm — does **not** await lan_tcp listen, Nostr relays, or BT availability.

package/docs/signaling.md

@@ -25,6 +25,7 @@ When set: send final offer/answer after ICE gathering, dedupe remote signals, qu
 `channels` selects which discovery/link media are active — `nostr`, `lan`, `bt`, `webrtc`. Semantics per channel key: `false` **disables**; any other value (`undefined`, `true`, or an object) **enables** — an object is merged over that channel's default config. Channels not mentioned keep their default enabled state.
 
 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)

package/federation/part_query/runtime.mjs

@@ -227,7 +227,7 @@ function mergeRowsWithSources(entries, maxHits, rowKey) {
 		try { return JSON.stringify(row) }
 		catch { return `\0${rows.length}` }
 	})
-	for (const entry of entries) {
+	for (const entry of entries)
 		for (const row of entry.rows || []) {
 			const key = keyOf(row)
 			if (!seen.has(key)) {
@@ -240,7 +240,7 @@ function mergeRowsWithSources(entries, maxHits, rowKey) {
 			}
 			if (entry.sourceNodeHash) sources.get(key).add(entry.sourceNodeHash)
 		}
-	}
+
 	return { rows, sources }
 }
 
@@ -325,10 +325,10 @@ function filterRowsBySource(rows, sources, rowKey, isSourceBlocked) {
 	return rows.filter(row => {
 		let key
 		if (rowKey) key = rowKey(row)
-		else {
+		else
 			try { key = JSON.stringify(row) }
 			catch { return true }
-		}
+
 		const set = sources.get(key)
 		if (!set || set.size === 0) return true
 		for (const source of set) if (!isSourceBlocked(source)) return true

package/index.mjs

@@ -13,6 +13,7 @@ import { registerLinkProvider } from './link/providers/index.mjs'
 import { ensureNodeDefaults, getNodeHash } from './node/identity.mjs'
 import {
 	closeNode,
+	configureNodeStorage,
 	getNodeDir,
 	getP2PFeatures,
 	initNode,
@@ -65,6 +66,7 @@ export {
 	attachNodeScopeDefaultFeatures,
 	closeNode,
 	configureLinkRegistry,
+	configureNodeStorage,
 	createGroupLinkSet,
 	createScopedLinkRoom,
 	ensureChannelAvailable,

package/mailbox/store.mjs

@@ -1,8 +1,5 @@
-import { mkdir, readFile } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
 import { isHex64 } from '../core/hexIds.mjs'
-import { jsonlMutexKey, writeJsonl } from '../dag/storage.mjs'
+import { jsonlMutexKey, readJsonl, writeJsonl } from '../dag/storage.mjs'
 import { mailboxStorePath } from '../node/user_paths.mjs'
 import { withAsyncMutex } from '../utils/async_mutex.mjs'
 
@@ -103,21 +100,7 @@ export function relayHopAfterWireIngress(wireHop, existingStoredHop) {
  * @returns {Promise<MailboxRecord[]>} 全部有效记录
  */
 async function readAll() {
-	try {
-		const text = await readFile(mailboxStorePath(), 'utf8')
-		/** @type {MailboxRecord[]} */
-		const rows = []
-		for (const line of text.split('\n')) {
-			const trimmed = line.trim()
-			if (!trimmed) continue
-			try {
-				rows.push(JSON.parse(trimmed))
-			}
-			catch { /* skip corrupt line */ }
-		}
-		return rows
-	}
-	catch { return [] }
+	return /** @type {MailboxRecord[]} */ await readJsonl(mailboxStorePath())
 }
 
 /**
@@ -125,13 +108,11 @@ async function readAll() {
  * @returns {Promise<void>}
  */
 async function writeAll(rows) {
-	const filePath = mailboxStorePath()
-	await mkdir(dirname(filePath), { recursive: true })
 	const now = Date.now()
 	const kept = pruneMailboxGlobalFair(
 		pruneMailboxBuckets(sortMailboxForRetention(rows.filter(record => record.expiresAt > now))),
 	)
-	await writeJsonl(filePath, kept)
+	await writeJsonl(mailboxStorePath(), kept)
 }
 
 /**

package/node/identity.mjs

@@ -42,6 +42,8 @@ function saveNodeFile(patch) {
 }
 
 /**
+ * 确保本地节点 seed 已持久化并返回。
+ * 只依赖本地存储目录（`configureNodeStorage` 或 `initNode` 提供），不要求运行中的节点。
  * @returns {string} 64 位十六进制 节点种子
  */
 export function ensureNodeSeed() {
@@ -54,6 +56,8 @@ export function ensureNodeSeed() {
 }
 
 /**
+ * 由本地 seed 派生本节点 nodeHash。
+ * 只依赖本地存储目录，不要求运行中的节点。
  * @returns {string} 本节点 64 hex nodeHash
  */
 export function getNodeHash() {
@@ -111,6 +115,8 @@ export function entityHashFromKeys(nodeHash, recoveryPubKeyHex) {
 }
 
 /**
+ * 由本地 nodeHash 与 recovery 公钥派生本节点 entityHash。
+ * 只依赖本地存储目录，不要求运行中的节点（联邦未启动时也可创建本地身份）。
  * @param {string} recoveryPubKeyHex 64 位十六进制 recovery 公钥
  * @returns {string | null} 本节点 entityHash
  */

package/node/instance.mjs

@@ -22,6 +22,13 @@ import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './
 /** @type {NodeRuntime | null} */
 let runtime = null
 
+/**
+ * 本地节点数据目录。与 `runtime` 解耦：身份 seed 等纯本地持久化只依赖存储目录，
+ * 不要求 `initNode()`（联邦未启动时也要能派生本地身份）。
+ * @type {string | null}
+ */
+let nodeStorageDir = null
+
 /** @type {Set<(event: string, payload?: unknown) => void>} */
 const changeListeners = new Set()
 
@@ -35,6 +42,28 @@ export function getRtcPolyfillCacheEpoch() {
 	return rtcPolyfillCacheEpoch
 }
 
+/**
+ * 配置本地节点数据目录（`node.json` / 身份 seed 等纯本地持久化位置），
+ * 不初始化节点运行时、不创建 disk 资源、不启动发现或连接。
+ *
+ * 配置后 `getNodeDir` / `ensureNodeSeed` / `getNodeHash` /
+ * `resolveLocalEntityHashFromRecoveryPubKeyHex` 可在无运行节点时使用；
+ * 之后以同一目录调用 `initNode` 会复用已持久化的 seed 与身份。
+ *
+ * 同目录重复配置为幂等；运行中的节点不允许切换到不同目录，须先 `closeNode()`。
+ * @param {{ nodeDir: string }} options - 本地节点数据目录
+ * @returns {string} 规范化为绝对路径后的目录
+ */
+export function configureNodeStorage(options) {
+	const rawDir = options?.nodeDir
+	if (typeof rawDir !== 'string' || !rawDir) throw new Error('p2p: configureNodeStorage requires nodeDir')
+	const nodeDir = path.resolve(rawDir)
+	if (runtime && runtime.nodeDir !== nodeDir)
+		throw new Error('p2p: running node uses another nodeDir — call closeNode() before reconfiguring storage')
+	nodeStorageDir = nodeDir
+	return nodeDir
+}
+
 /**
  * @param {{ nodeDir: string, entityStore?: import('./entity_store.mjs').EntityStore }} options - 节点目录与可选 entity store
  * @returns {NodeRuntime} 初始化后的运行时
@@ -43,7 +72,7 @@ export function initNode(options) {
 	if (runtime) throw new Error('p2p: initNode already called — use setNodeLogger / setSignalingRuntimeConfig or closeNode')
 	if (options?.logger !== undefined || options?.signaling !== undefined)
 		throw new Error('p2p: initNode only accepts nodeDir/entityStore — use setNodeLogger / setSignalingRuntimeConfig')
-	const nodeDir = path.resolve(options.nodeDir)
+	const nodeDir = options?.nodeDir == null ? nodeStorageDir : configureNodeStorage({ nodeDir: options.nodeDir })
 	if (!nodeDir) throw new Error('p2p: initNode requires nodeDir')
 	const entityStore = options.entityStore ?? createFsEntityStore(path.join(nodeDir, 'entities'))
 	runtime = {
@@ -123,10 +152,12 @@ export function getP2PFeatures() {
 }
 
 /**
- * @returns {string} 节点数据目录绝对路径
+ * @returns {string} 节点数据目录绝对路径；未配置且节点未初始化时抛错
  */
 export function getNodeDir() {
-	return getNode().nodeDir
+	if (runtime) return runtime.nodeDir
+	if (nodeStorageDir) return nodeStorageDir
+	throw new Error('p2p: node storage not configured — call configureNodeStorage() or initNode() first')
 }
 
 /**
@@ -164,12 +195,13 @@ export function onNodeChange(listener) {
 }
 
 /**
- * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时与监听器。
- * 之后可用 initNode 重新引导。
+ * 关闭节点：释放全部文件句柄（chunk 读/写流等）并清空运行时、存储目录配置与监听器。
+ * 之后可用 initNode / configureNodeStorage 重新引导。
  * @returns {Promise<void>}
  */
 export async function closeNode() {
 	runtime = null
+	nodeStorageDir = null
 	changeListeners.clear()
 	rtcPolyfillCacheEpoch++
 	await closeAllFileStreams()

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.43",
+	"version": "0.0.46",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",
@@ -15,7 +15,7 @@
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/steve02081504/fount-p2p.git",
-		"directory": "."
+		"directory": "js"
 	},
 	"engines": {
 		"node": ">=20"

package/pages/index.mjs

@@ -32,6 +32,10 @@ function startLive() {
 	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）`

package/timeline/prune.mjs

@@ -1,13 +1,14 @@
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
 import { topologicalCanonicalOrder } from '../dag/index.mjs'
-import { readJsonl, writeJsonlSynced } from '../dag/storage.mjs'
+import { jsonlMutexKey, readJsonlEntries, writeJsonlLines } from '../dag/storage.mjs'
 import { invalidateTopologicalOrderMemo } from '../federation/topo_order_memo.mjs'
 import { descendantClosureFromTip } from '../governance/branch.mjs'
+import { withAsyncMutex } from '../utils/async_mutex.mjs'
 
 /**
  * 将 events.jsonl 裁剪为 checkpoint 起后代闭包（连通子图，非拓扑下标切片）。
+ *
+ * 整个读-算-写在 `jsonlMutexKey(eventsFilePath)` 锁内完成，避免与并发 append 竞态；
+ * 写回的是保留行的原始字节（非 sanitize 后的重序列化），保持无损失。
  * @param {string} eventsFilePath events.jsonl 路径
  * @param {object | null} checkpoint 含 checkpoint_event_id 的快照
  * @param {(row: object) => object} [sanitize] 行规范化
@@ -16,24 +17,27 @@ import { descendantClosureFromTip } from '../governance/branch.mjs'
 export async function pruneEventsJsonlAfterCheckpoint(eventsFilePath, checkpoint, sanitize = row => row) {
 	const tipId = checkpoint?.checkpoint_event_id
 	if (!tipId) return { pruned: false, kept: 0, dropped: 0 }
-	const events = await readJsonl(eventsFilePath, { sanitize })
-	if (!events.length) return { pruned: false, kept: 0, dropped: 0 }
-	const byId = new Map(events.map(dagEvent => [dagEvent.id, dagEvent]))
-	if (!byId.has(tipId)) return { pruned: false, kept: events.length, dropped: 0 }
+	return withAsyncMutex(jsonlMutexKey(eventsFilePath), async () => {
+		const entries = await readJsonlEntries(eventsFilePath, { sanitize })
+		if (!entries.length) return { pruned: false, kept: 0, dropped: 0 }
+		const byId = new Map(entries.map(entry => [entry.row.id, entry.row]))
+		const rawById = new Map(entries.map(entry => [entry.row.id, entry.raw]))
+		if (!byId.has(tipId)) return { pruned: false, kept: entries.length, dropped: 0 }
 
-	const keepIds = descendantClosureFromTip(tipId, byId)
-	const order = topologicalCanonicalOrder(events.map(dagEvent => ({
-		id: dagEvent.id,
-		prev_event_ids: dagEvent.prev_event_ids,
-		hlc: dagEvent.hlc,
-		node_id: dagEvent.node_id,
-		sender: dagEvent.sender,
-	})))
-	const kept = order.map(id => byId.get(id)).filter(ev => ev && keepIds.has(ev.id))
-	const dropped = events.length - kept.length
-	if (dropped <= 0) return { pruned: false, kept: kept.length, dropped: 0 }
-	await mkdir(dirname(eventsFilePath), { recursive: true })
-	await writeJsonlSynced(eventsFilePath, kept)
-	invalidateTopologicalOrderMemo(eventsFilePath)
-	return { pruned: true, kept: kept.length, dropped }
+		const keepIds = descendantClosureFromTip(tipId, byId)
+		const order = topologicalCanonicalOrder(entries.map(entry => ({
+			id: entry.row.id,
+			prev_event_ids: entry.row.prev_event_ids,
+			hlc: entry.row.hlc,
+			node_id: entry.row.node_id,
+			sender: entry.row.sender,
+		})))
+		const keptIds = order.filter(id => keepIds.has(id))
+		const dropped = entries.length - keptIds.length
+		if (dropped <= 0) return { pruned: false, kept: keptIds.length, dropped: 0 }
+		const keptRaws = keptIds.map(id => rawById.get(id)).filter(raw => raw !== undefined)
+		await writeJsonlLines(eventsFilePath, keptRaws)
+		invalidateTopologicalOrderMemo(eventsFilePath)
+		return { pruned: true, kept: keptIds.length, dropped }
+	})
 }

package/timeline/retention.mjs

@@ -1,13 +1,13 @@
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
-
 import { topologicalCanonicalOrder } from '../dag/index.mjs'
-import { readJsonl, writeJsonlSynced } from '../dag/storage.mjs'
+import { jsonlMutexKey, readJsonlEntries, writeJsonlLines } from '../dag/storage.mjs'
 import { invalidateTopologicalOrderMemo } from '../federation/topo_order_memo.mjs'
 import { computeDagTipIdsFromEvents, selectConsensusBranchTip } from '../governance/branch.mjs'
 import { computeRetentionKeepIds } from '../node/retention_policy.mjs'
+import { withAsyncMutex } from '../utils/async_mutex.mjs'
 
 /**
+ * 整个读-算-写在 `jsonlMutexKey(eventsFilePath)` 锁内完成，避免与并发 append 竞态；
+ * 写回的是保留行的原始字节（非 sanitize 后的重序列化），保持无损失。
  * @param {string} eventsFilePath events.jsonl 路径
  * @param {object | null} checkpointHint 检查点提示
  * @param {{ maxDepth: number, maxMs: number, anchorTypes: Set<string> }} policy 保留策略
@@ -20,35 +20,39 @@ export async function enforceTimelineEventRetention(
 	policy,
 	sanitize = row => row,
 ) {
-	const events = await readJsonl(eventsFilePath, { sanitize })
-	if (!events.length) return { pruned: false, kept: 0, dropped: 0 }
-	const maxDepth = Math.max(256, Number(policy.maxDepth) || 200_000)
-	const maxMs = Math.max(3_600_000, Number(policy.maxMs) || 365 * 24 * 3600 * 1000)
-	const cutoffWall = Date.now() - maxMs
-	const byId = new Map(events.map(e => [e.id, e]))
-	const order = topologicalCanonicalOrder(events.map(e => ({
-		id: e.id,
-		prev_event_ids: e.prev_event_ids,
-		hlc: e.hlc,
-		node_id: e.node_id,
-		sender: e.sender,
-	})))
-	const tips = computeDagTipIdsFromEvents(events)
-	const branchTipId = selectConsensusBranchTip(tips, byId)
-	const checkpointTipId = checkpointHint?.checkpoint_event_id || null
-	const keepIds = computeRetentionKeepIds(order, byId, {
-		maxDepth,
-		cutoffWall,
-		anchorTypes: policy.anchorTypes,
-		checkpointTipId,
-		branchTipId,
+	return withAsyncMutex(jsonlMutexKey(eventsFilePath), async () => {
+		const entries = await readJsonlEntries(eventsFilePath, { sanitize })
+		if (!entries.length) return { pruned: false, kept: 0, dropped: 0 }
+		const maxDepth = Math.max(256, Number(policy.maxDepth) || 200_000)
+		const maxMs = Math.max(3_600_000, Number(policy.maxMs) || 365 * 24 * 3600 * 1000)
+		const cutoffWall = Date.now() - maxMs
+		const events = entries.map(entry => entry.row)
+		const rawById = new Map(entries.map(entry => [entry.row.id, entry.raw]))
+		const byId = new Map(events.map(e => [e.id, e]))
+		const order = topologicalCanonicalOrder(events.map(e => ({
+			id: e.id,
+			prev_event_ids: e.prev_event_ids,
+			hlc: e.hlc,
+			node_id: e.node_id,
+			sender: e.sender,
+		})))
+		const tips = computeDagTipIdsFromEvents(events)
+		const branchTipId = selectConsensusBranchTip(tips, byId)
+		const checkpointTipId = checkpointHint?.checkpoint_event_id || null
+		const keepIds = computeRetentionKeepIds(order, byId, {
+			maxDepth,
+			cutoffWall,
+			anchorTypes: policy.anchorTypes,
+			checkpointTipId,
+			branchTipId,
+		})
+		if (keepIds.size >= events.length) return { pruned: false, kept: events.length, dropped: 0 }
+		const keptIds = order.filter(id => keepIds.has(id))
+		const dropped = events.length - keptIds.length
+		if (dropped <= 0) return { pruned: false, kept: keptIds.length, dropped: 0 }
+		const keptRaws = keptIds.map(id => rawById.get(id)).filter(raw => raw !== undefined)
+		await writeJsonlLines(eventsFilePath, keptRaws)
+		invalidateTopologicalOrderMemo(eventsFilePath)
+		return { pruned: true, kept: keptIds.length, dropped }
 	})
-	if (keepIds.size >= events.length) return { pruned: false, kept: events.length, dropped: 0 }
-	const kept = order.map(id => byId.get(id)).filter(ev => ev && keepIds.has(ev.id))
-	const dropped = events.length - kept.length
-	if (dropped <= 0) return { pruned: false, kept: kept.length, dropped: 0 }
-	await mkdir(dirname(eventsFilePath), { recursive: true })
-	await writeJsonlSynced(eventsFilePath, kept)
-	invalidateTopologicalOrderMemo(eventsFilePath)
-	return { pruned: true, kept: kept.length, dropped }
 }

package/utils/async_mutex.mjs

@@ -25,13 +25,21 @@ function mutexState(lockKey) {
  */
 function releaseMutex(lockKey, state) {
 	const next = state.queue.shift()
-	if (next) setTimeout(next, 0)
+	if (next) queueMicrotask(next)
 	else {
 		state.locked = false
 		mutexes.delete(lockKey)
 	}
 }
 
+/**
+ * 当前存活的互斥键数量（仅供测试观察锁表是否回落到基线）。
+ * @returns {number} `mutexes` 中的键数量
+ */
+export function activeMutexCount() {
+	return mutexes.size
+}
+
 /**
  * @param {string} key 锁键
  * @param {() => Promise<T>} criticalSection 临界区
@@ -39,15 +47,14 @@ function releaseMutex(lockKey, state) {
  * @template T
  */
 export async function withAsyncMutex(key, criticalSection) {
-	const lockKey = key
-	const state = mutexState(lockKey)
+	const state = mutexState(key)
 	return new Promise((resolve, reject) => {
 		/** 执行临界区并最终释放锁 */
 		const run = () => {
 			Promise.resolve()
 				.then(criticalSection)
 				.then(resolve, reject)
-				.finally(() => releaseMutex(lockKey, state))
+				.finally(() => releaseMutex(key, state))
 		}
 		if (state.locked) state.queue.push(run)
 		else {

package/utils/shuffle.mjs

@@ -7,7 +7,7 @@
 export function shuffleInPlace(arr) {
 	for (let i = arr.length - 1; i > 0; i--) {
 		const j = Math.floor(Math.random() * (i + 1))
-		;[arr[i], arr[j]] = [arr[j], arr[i]]
+			;[arr[i], arr[j]] = [arr[j], arr[i]]
 	}
 	return arr
 }

package/wire/adapter.mjs

@@ -10,4 +10,4 @@
  */
 
 /** Wire 适配器与上下文的类型导出（运行时代码见各 wire 模块）。 */
-export {}
+export { }