@steve02081504/fount-p2p 0.0.44 → 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.
@@ -76,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/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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@steve02081504/fount-p2p",
-	"version": "0.0.44",
+	"version": "0.0.46",
 	"description": "fount federation P2P layer — link, trust graph, mailbox, DAG, EVFS.",
 	"keywords": [
 		"network",

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 { }