@steve02081504/fount-p2p 0.0.39 → 0.0.41

package/AGENTS.md

@@ -39,7 +39,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 
 ## Tests / tools
 
-- `npm test` — pure + integration (Node; `--test-force-exit`)
+- `npm test` — pure + integration + frontend (Node; `--test-force-exit`)
 - `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))
@@ -73,7 +73,7 @@ Deno / native / BT: [runtime.md](docs/runtime.md).
 
 | File | Directory |
 |---|---|
-| `tunables.json` | `reputation/`, `trust_graph/`, `mailbox/`, `governance/`, `dag/` |
+| `tunables.json` | `transport/`, `infra/`, `reputation/`, `trust_graph/`, `mailbox/`, `governance/`, `dag/` |
 | `part_query.tunables.json` | `schemas/` |
 
 Sim harness: `sim/tunables_bundle.mjs` (dev-only). See [sim/AGENTS.md](sim/AGENTS.md).

package/docs/evfs.md

@@ -9,6 +9,17 @@ Day-to-day package rules: [AGENTS.md](../AGENTS.md). Implementation: `files/` (`
 | Ciphertext chunks (CAS) | `{nodeDir}/chunks/` |
 | Manifests | `{EntityStoreRoot}/{entityHash}/files/{path}.manifest.json` |
 
+## Chunk garbage collection
+
+Chunk store is content-addressed and **write-only**: overwriting or deleting a file only rewrites/removes the manifest, old blocks stay behind forever. Reclamation is explicit, via `files/gc.mjs`:
+
+- `mapChunkGarbage()` — read-only scan. Root set = the `parts[].hash` of **every** on-disk manifest (local writes, public cache, targeted non-public cache). Returns `{ manifests, brokenManifests, referenced, candidates: [{hash,size}], freedBytes }` plus zeroed delete counters. No side effects.
+- `cleanChunkGarbage({ targets? })` — with `targets` (hashes or `{hash}`) it removes only that set without scanning and without touching manifests; without `targets` it scans, deletes every orphan chunk, and auto-removes manifests that fail `normalizeFileManifest` (reported as `brokenDeleted`).
+- `deleteFileManifest(ownerEntityHash, logicalPath)` — explicit manifest delete (orphans its chunks for the next GC); requires the entity store to implement `deleteManifest`.
+- `deleteChunk(hash)` — standalone primitive (deleting a chunk that is still referenced by a manifest breaks the file).
+
+Concurrency: `putChunk` / `putChunkFromStream` / `deleteChunk` / the GC delete phase share one in-process mutex (`withChunkStoreLock`), so a GC never unlinks a block mid-write. Unlink is best-effort on ENOENT and skips EBUSY/EPERM (Windows open-handle = block is being streamed; retried next GC). Lock is process-local — do not run GC in a second process against the same `nodeDir`.
+
 ## Public publish / verify
 
 - `publishPublicFile` signs with the recovery key.
@@ -22,12 +33,19 @@ Day-to-day package rules: [AGENTS.md](../AGENTS.md). Implementation: `files/` (`
 | --- | --- |
 | Default options | Node-scope fanout; **only** signed public manifests accepted; no cache write |
 | Local public hit with `publicSig` | Return immediately; fanout revalidates in the background. With `cache: true`, write only when remote `publishedAt` is newer |
+| `revalidate: true` on local public hit | Block until the fanout settles; prefer the newer `publishedAt` (write back when `cache: true`), else fall back to the local copy (offline-safe) |
 | Local non-public hit | Return immediately (**targeted mode only**); no revalidation (no publish order to compare); public mode refuses non-public local |
 | `fanoutTargets` given | Fanout **only** to that node set; accepts signed public **or** normalized non-public manifests; non-public hit is cached locally by default |
 | Same key in flight | Deduped via `utils/inflight_table` (key includes `public`/`targeted` mode) |
 
 Outer caller timeouts must **not** abort the in-flight work — background fill continues after the caller gives up.
 
+## `fetchChunk` / public-file chunk reads
+
+- `fetchChunk` accepts the same `fanoutTargets` as `fetchManifest`. With targets it fanouts `fed_chunk_get` **only** to that node set; without targets it falls back to node-scope fanout. Same `username`+chunk hash+mode (`targeted`/`public`) is deduped in-flight.
+- `readPublicFile` / `readManifestPlaintext` forward `options.fanoutTargets` to both the manifest fetch and the chunk fetch, so a cross-node public read can pull profile/avatar content straight from the owner node instead of depending on the node-scope fanout.
+- The public (non-targeted) fanout does **not** block the request window on dialing the whole peer pool: already-linked / group-room-reachable peers are sent immediately, and unreachable peers are dialed in the background and re-sent once linked. (`ensureLinkToNode` no longer gates the send.)
+
 ## Non-public (ACL-gated) manifests
 
 - `file-master-key-wrap` / `vault-wrap` / `identity-wrap` manifests carry no author signature, so the remote-acquisition trust boundary is **not** a signature — it is the **fanout target set** plus the **serving node's authorization**.

package/files/chunk/fetch.mjs

@@ -26,10 +26,14 @@ const chunkInflight = createInflightTable({
  *   ciphertextHash: string,
  *   ownerEntityHash?: string,
  *   groupId?: string,
+ *   fanoutTargets?: string[],
  * }} FetchChunkContext
  */
 
 /**
+ * 拉取密文块。默认走 node-scope public 语义；
+ * 传入 `fanoutTargets` 时只向目标集 fanout（public 文件定向拉取，如 profile/avatar 直接向 owner 节点取块）。
+ * 同 username+hash+模式（含规范化目标集）in-flight 去重；本地已缓存块直接返回。
  * @param {FetchChunkContext} context 上下文
  * @returns {Promise<Uint8Array | null>} 密文块
  */
@@ -50,7 +54,7 @@ export async function fetchChunk(context) {
 
 	const shared = beginFedFanoutFetch({
 		inflight: chunkInflight,
-		inflightKey: `${username}\0${hash}`,
+		inflightKeyBase: `${username}\0${hash}`,
 		username,
 		action: 'fed_chunk_get',
 		/**
@@ -69,6 +73,7 @@ export async function fetchChunk(context) {
 			chunkHash: hash,
 			ownerEntityHash: context.ownerEntityHash,
 		}),
+		fanoutTargets: context.fanoutTargets,
 	})
 	if (!shared) return null
 

package/files/chunk/store.mjs

@@ -7,6 +7,21 @@ import { pipeline } from 'node:stream/promises'
 import { isHex64 } from '../../core/hexIds.mjs'
 import { trackFileStream } from '../../node/handles.mjs'
 import { getNodeDir } from '../../node/instance.mjs'
+import { withAsyncMutex } from '../../utils/async_mutex.mjs'
+
+/** chunk store 互斥键：GC 删除与写入互斥。 */
+const CHUNK_STORE_LOCK_KEY = 'chunk-store'
+
+/**
+ * chunk store 全局互斥锁（进程内）。GC 删除阶段与 `putChunk`/`putChunkFromStream` 共用，
+ * 避免「GC unlink 与写入竞争」。单进程假设，不跨进程。
+ * @template T
+ * @param {() => Promise<T>} criticalSection 临界区
+ * @returns {Promise<T>} 临界区返回值
+ */
+export function withChunkStoreLock(criticalSection) {
+	return withAsyncMutex(CHUNK_STORE_LOCK_KEY, criticalSection)
+}
 
 /**
  * @returns {string} `{nodeDir}/chunks`
@@ -60,9 +75,7 @@ export function createChunkReadStream(hash) {
  * @returns {Promise<void>}
  */
 export async function putChunk(hash, data) {
-	const filePath = chunkStorePath(hash)
-	await fsp.mkdir(dirname(filePath), { recursive: true })
-	await fsp.writeFile(filePath, Buffer.from(data))
+	return withChunkStoreLock(() => writeChunkFile(hash, Buffer.from(data)))
 }
 
 /**
@@ -71,7 +84,49 @@ export async function putChunk(hash, data) {
  * @returns {Promise<void>}
  */
 export async function putChunkFromStream(hash, readable) {
+	return withChunkStoreLock(async () => {
+		const filePath = chunkStorePath(hash)
+		await fsp.mkdir(dirname(filePath), { recursive: true })
+		await pipeline(readable, trackFileStream(fs.createWriteStream(filePath)))
+	})
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @param {string | Buffer | Uint8Array} data 块数据
+ * @returns {Promise<void>} 直接写文件（无锁；调用方须持 `withChunkStoreLock`）
+ */
+async function writeChunkFile(hash, data) {
 	const filePath = chunkStorePath(hash)
 	await fsp.mkdir(dirname(filePath), { recursive: true })
-	await pipeline(readable, trackFileStream(fs.createWriteStream(filePath)))
+	await fsp.writeFile(filePath, data)
+}
+
+/**
+ * @param {string} hash 64 位十六进制
+ * @returns {Promise<{ deleted: boolean, size: number }>} 删除结果；`deleted:false` 表示仍在被读（Windows open-handle）
+ */
+export async function unlinkChunkFile(hash) {
+	const filePath = chunkStorePath(hash)
+	try {
+		const { size } = await fsp.stat(filePath)
+		await fsp.unlink(filePath)
+		return { deleted: true, size }
+	}
+	catch (error) {
+		const code = /** @type {NodeJS.ErrnoException} */ error.code
+		if (code === 'ENOENT') return { deleted: true, size: 0 }
+		// Windows 上文件被读流打开时 unlink 会 EBUSY/EPERM——视为仍在使用，留给下次 GC。
+		if (code === 'EBUSY' || code === 'EPERM') return { deleted: false, size: 0 }
+		throw error
+	}
+}
+
+/**
+ * 删除单个 chunk（带互斥锁）。重复删除视为成功。
+ * @param {string} hash 64 位十六进制
+ * @returns {Promise<{ deleted: boolean, size: number }>} 删除结果
+ */
+export async function deleteChunk(hash) {
+	return withChunkStoreLock(() => unlinkChunkFile(hash))
 }

package/files/evfs.mjs

@@ -32,7 +32,7 @@ function transferKeyDependenciesForReplica(replicaUsername, manifest) {
 /**
  * @param {string} username 拉取身份
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @param {{ fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ fetchChunk?: Function, fanoutTargets?: string[] }} [options] miss 拉取
  * @returns {Promise<boolean>} 全部 part 是否已就位
  */
 async function ensureManifestPartsLocal(username, manifest, options = {}) {
@@ -43,6 +43,7 @@ async function ensureManifestPartsLocal(username, manifest, options = {}) {
 			ciphertextHash: part.hash,
 			ownerEntityHash: manifest.ownerEntityHash,
 			groupId: manifest.transferKeyDescriptor.groupId,
+			fanoutTargets: options.fanoutTargets,
 		})
 		if (!fetchedChunk) return false
 		await putChunk(part.hash, fetchedChunk)
@@ -67,6 +68,20 @@ export async function saveFileManifest(manifest) {
 	await getEntityStore().writeManifest(manifest.ownerEntityHash, manifest.logicalPath, manifest)
 }
 
+/**
+ * 删除本机已写盘 manifest；其引用的 chunk 孤儿化后由 `cleanChunkGarbage` 回收。
+ * @param {string} ownerEntityHash 所有者
+ * @param {string} logicalPath 路径
+ * @returns {Promise<void>} 删除成功或不存在
+ */
+export async function deleteFileManifest(ownerEntityHash, logicalPath) {
+	const entityStore = getEntityStore()
+	if (entityStore.deleteManifest)
+		await entityStore.deleteManifest(ownerEntityHash, logicalPath)
+	else
+		throw new Error('entityStore lacks deleteManifest')
+}
+
 /**
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {Array<Buffer | Uint8Array>} partBytes 密文块
@@ -80,7 +95,7 @@ export async function storeManifestParts(manifest, partBytes) {
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function, fanoutTargets?: string[] }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
 export async function readManifestPlaintext(replicaUsername, manifest, options = {}) {
@@ -104,7 +119,7 @@ export async function readManifestPlaintext(replicaUsername, manifest, options =
 /**
  * @param {string} replicaUsername 副本用户名
  * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
- * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function, fanoutTargets?: string[] }} [options] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
 export async function readManifestPlaintextStream(replicaUsername, manifest, options = {}) {
@@ -215,10 +230,11 @@ export async function putFileManifestFromStream(parameters) {
 
 /**
  * 读取实体公开文件：本地 miss 时经网络取回签名 manifest，chunk miss 走既有 fetchChunk。
+ * 传入 `fanoutTargets` 时 manifest 与 chunk 拉取均定向到目标集（public 文件跨节点直取 owner 节点，避免 node-scope 大扇出）。
  * @param {string} replicaUsername 副本用户名
  * @param {string} entityHash owner entityHash
  * @param {string} logicalPath EVFS 逻辑路径
- * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
+ * @param {{ username?: string, fetchChunk?: Function, revalidate?: boolean, fanoutTargets?: string[] }} [options] miss 拉取；`revalidate` 强制阻塞等待 fanout 择新
  * @returns {Promise<Buffer | null>} 明文或 null
  */
 export async function readPublicFile(replicaUsername, entityHash, logicalPath, options = {}) {
@@ -228,6 +244,8 @@ export async function readPublicFile(replicaUsername, entityHash, logicalPath, o
 		ownerEntityHash: entityHash,
 		logicalPath,
 		cache: true,
+		revalidate: options.revalidate === true,
+		fanoutTargets: options.fanoutTargets,
 	})
 	if (!manifest) return null
 	return readManifestPlaintext(replicaUsername, manifest, options)

package/files/fed/fetch_shared.mjs

@@ -1,14 +1,15 @@
 import { randomUUID } from 'node:crypto'
 
 import { resolveNodeHash } from '../chunk/provider_registry.mjs'
-import { fanoutFedFetch } from '../fetch_fanout.mjs'
+import { canonicalizeFanoutTargets, fanoutFedFetch } from '../fetch_fanout.mjs'
 
 /**
  * inflight + pending wait + fanout 共用骨架。
+ * 规范化目标集并拼入 inflight key：`fanoutTargets` 为数组（含空）即定向模式，undefined 为 node-scope public 模式。
  * @template T
  * @param {{
  *   inflight: { acquire: (key: string, start: () => { done: Promise<T | null>, cancel: () => void }) => Promise<T | null> | null },
- *   inflightKey: string,
+ *   inflightKeyBase: string,
  *   username: string,
  *   action: string,
  *   registerWait: (requestId: string) => { done: Promise<T | null>, cancel: () => void },
@@ -19,20 +20,23 @@ import { fanoutFedFetch } from '../fetch_fanout.mjs'
  */
 export function beginFedFanoutFetch({
 	inflight,
-	inflightKey,
+	inflightKeyBase,
 	username,
 	action,
 	registerWait,
 	buildPayload,
 	fanoutTargets,
 }) {
+	const targeted = Array.isArray(fanoutTargets)
+	const canonicalTargets = targeted ? canonicalizeFanoutTargets(fanoutTargets) : undefined
+	const inflightKey = `${inflightKeyBase}\0${targeted ? 'targeted' : 'public'}` + (canonicalTargets?.length ? `\0${canonicalTargets.join('\0')}` : '')
 	return inflight.acquire(inflightKey, () => {
 		const requestId = randomUUID()
 		const wait = registerWait(requestId)
 		void (async () => {
 			try {
 				const { nodeHash } = await resolveNodeHash(username)
-				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash), fanoutTargets)
+				await fanoutFedFetch(username, action, buildPayload(requestId, nodeHash), canonicalTargets)
 			}
 			catch { /* pending wait 超时/cancel 负责 settle */ }
 		})()

package/files/fetch_fanout.mjs

@@ -32,6 +32,7 @@ export function canonicalizeFanoutTargets(targets) {
 /**
  * 全局 miss 请求扇出：先向已知 peer 定向发送，再 trust-graph top-K fanout。
  * 已直连 / follow hint peer 可能不在 trust-graph top-K（非成员 emoji CAS / Social 预览路径），故先定向发送。
+ * 拨号不阻塞请求窗口：已直连 peer 立即经现有链路投递，未直连 peer 先经群房间/overlay 尝试并后台拨号补发。
  * @param {string} username 用户
  * @param {string} action wire action 名
  * @param {object} payload 请求载荷
@@ -52,8 +53,20 @@ export async function fanoutFedFetch(username, action, payload, fanoutTargets) {
 
 	const graph = await trustGraph.buildMergedGraph(username)
 	const peerTargets = fetchPeerTargets()
-	await Promise.all(peerTargets.map(nodeHash => ensureLinkToNode(nodeHash).catch(() => null)))
-	for (const nodeHash of peerTargets)
-		void trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+	// 已直连 peer 立即经现有链路投递；其余 peer 后台并行：先经群房间/overlay 尝试投递，同时拨号，拨通且首投失败再补发。
+	// 全程不阻塞请求窗口（大 peer 池下 await 全量拨号会超窗口）。
+	const linked = new Set(listLinks().map(({ nodeHash }) => nodeHash))
+	for (const nodeHash of peerTargets) {
+		if (linked.has(nodeHash)) {
+			void trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+			continue
+		}
+		const dialed = ensureLinkToNode(nodeHash).catch(() => null)
+		void trustGraph.sendToNode(username, nodeHash, action, payload, graph).then(async sent => {
+			if (sent) return
+			const link = await dialed
+			if (link) await trustGraph.sendToNode(username, nodeHash, action, payload, graph)
+		})
+	}
 	await trustGraph.fanoutToTopNodes(username, action, payload, FEDERATION_CHUNK_FETCH_FANOUT_K)
 }

package/files/gc.mjs

@@ -0,0 +1,192 @@
+import fsp from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { isHex64 } from '../core/hexIds.mjs'
+import { getEntityStore, getNodeLogger } from '../node/instance.mjs'
+
+import {
+	chunkStoreRoot,
+	unlinkChunkFile,
+	withChunkStoreLock,
+} from './chunk/store.mjs'
+import { normalizeFileManifest } from './manifest/normalize.mjs'
+
+/**
+ * @typedef {{ hash: string, size: number }} GcChunkTarget
+ */
+
+/**
+ * @typedef {{
+ *   manifests: number,
+ *   brokenManifests: Array<{ ownerEntityHash: string, logicalPath: string }>,
+ *   referenced: number,
+ *   candidates: Array<GcChunkTarget>,
+ *   deleted: number,
+ *   retained: number,
+ *   freedBytes: number,
+ *   brokenDeleted: number,
+ * }} GarbageCollectionReport
+ */
+
+/**
+ * 纯读扫描：以全部写盘 manifest 的 `parts[].hash` 为根集，枚举 `chunks/` 孤儿块与坏 manifest。
+ * 无副作用（不删文件）。
+ * @returns {Promise<GarbageCollectionReport>} 扫描报告
+ */
+async function scanChunkGarbage() {
+	const entityStore = getEntityStore()
+	const referenced = new Set()
+	const brokenManifests = []
+	let manifests = 0
+
+	const entityHashes = await entityStore.listEntityHashes()
+	for (const entityHash of entityHashes) {
+		const logicalPaths = await entityStore.listEntityFiles(entityHash)
+		for (const logicalPath of logicalPaths) {
+			manifests++
+			const raw = await entityStore.readManifest(entityHash, logicalPath)
+			const normalized = normalizeFileManifest(raw)
+			if (!normalized) {
+				brokenManifests.push({ ownerEntityHash: entityHash, logicalPath })
+				continue
+			}
+			for (const part of normalized.parts)
+				referenced.add(part.hash)
+		}
+	}
+
+	/** @type {GcChunkTarget[]} */
+	const candidates = []
+	let freedBytes = 0
+	let prefixEntries
+	try {
+		prefixEntries = await fsp.readdir(chunkStoreRoot(), { withFileTypes: true })
+	}
+	catch {
+		prefixEntries = []
+	}
+	for (const prefixEntry of prefixEntries) {
+		if (!prefixEntry.isDirectory() || prefixEntry.name.length !== 2) continue
+		let files
+		try {
+			files = await fsp.readdir(join(chunkStoreRoot(), prefixEntry.name))
+		}
+		catch { continue }
+		for (const name of files) {
+			if (!name.endsWith('.bin')) continue
+			const hash = name.slice(0, -4)
+			if (!isHex64(hash) || referenced.has(hash)) continue
+			const size = await chunkFileSize(join(chunkStoreRoot(), prefixEntry.name, name))
+			candidates.push({ hash, size })
+			freedBytes += size
+		}
+	}
+
+	return {
+		manifests,
+		brokenManifests,
+		referenced: referenced.size,
+		candidates,
+		deleted: 0,
+		retained: 0,
+		freedBytes,
+		brokenDeleted: 0,
+	}
+}
+
+/**
+ * @param {string} filePath chunk 文件绝对路径
+ * @returns {Promise<number>} 文件字节数；stat 失败为 0
+ */
+async function chunkFileSize(filePath) {
+	try {
+		const { size } = await fsp.stat(filePath)
+		return size
+	}
+	catch { return 0 }
+}
+
+/**
+ * 持锁删除一批 chunk，统计删除结果并顺带清理已空前缀目录。
+ * @param {string[]} hashes 待删 64 位 hex 集合
+ * @returns {Promise<{ deleted: number, retained: number, freedBytes: number }>} 删除结果统计
+ */
+async function removeChunkHashes(hashes) {
+	let deleted = 0
+	let retained = 0
+	let freedBytes = 0
+	const emptiedPrefixes = new Set()
+	await withChunkStoreLock(async () => {
+		for (const hash of hashes) {
+			const result = await unlinkChunkFile(hash)
+			if (result.deleted) {
+				deleted++
+				freedBytes += result.size
+				emptiedPrefixes.add(hash.slice(0, 2))
+			}
+			else retained++
+		}
+		for (const prefix of emptiedPrefixes) try {
+			await fsp.rmdir(join(chunkStoreRoot(), prefix))
+		} catch { /* 目录非空或已被删，忽略 */ }
+	})
+	return { deleted, retained, freedBytes }
+}
+
+/**
+ * 扫描并报告 chunk 垃圾（只读，不删除）。
+ * 根集 = 全部写盘 manifest 的 `parts[].hash`（含公共/非 public 缓存）；`chunks/` 中不在根集的可回收。
+ * @returns {Promise<GarbageCollectionReport>} 统计报告
+ */
+export async function mapChunkGarbage() {
+	return scanChunkGarbage()
+}
+
+/**
+ * 清理 chunk 垃圾。缺省 `targets` 时先扫描再删除（并自动清除扫描到的坏 manifest）；
+ * 提供 `targets` 时只按给定集合删除，不做扫描、不碰 manifest。
+ * @param {{ targets?: Array<string | GcChunkTarget> }} [options] 可选显式目标集
+ * @returns {Promise<GarbageCollectionReport>} 执行报告
+ */
+export async function cleanChunkGarbage(options = {}) {
+	const targets = Array.isArray(options.targets)
+
+	/** @type {string[]} */
+	let hashes
+	if (targets) {
+		hashes = options.targets.map(target => {
+			const hash = typeof target === 'string' ? target : target?.hash
+			if (!isHex64(hash)) throw new Error(`cleanChunkGarbage: invalid chunk hash ${hash}`)
+			return hash
+		})
+		const { deleted, retained, freedBytes } = await removeChunkHashes(hashes)
+		return {
+			manifests: 0,
+			brokenManifests: [],
+			referenced: 0,
+			candidates: hashes.map(hash => ({ hash, size: 0 })),
+			deleted,
+			retained,
+			freedBytes,
+			brokenDeleted: 0,
+		}
+	}
+
+	const snapshot = await scanChunkGarbage()
+	const entityStore = getEntityStore()
+	const logger = getNodeLogger()
+	let brokenDeleted = 0
+	if (snapshot.brokenManifests.length) {
+		for (const broken of snapshot.brokenManifests) {
+			if (!entityStore.deleteManifest) break
+			await entityStore.deleteManifest(broken.ownerEntityHash, broken.logicalPath)
+			brokenDeleted++
+		}
+		logger?.info?.(`chunk GC: removed ${brokenDeleted} broken manifest(s)`)
+	}
+
+	const { deleted, retained, freedBytes } = await removeChunkHashes(
+		snapshot.candidates.map(candidate => candidate.hash),
+	)
+	return { ...snapshot, deleted, retained, freedBytes, brokenDeleted }
+}

package/files/manifest/fetch.mjs

@@ -30,9 +30,10 @@ const manifestInflight = createInflightTable({
  * 拉取 manifest。默认走 node-scope public 语义（仅接受验签公开 manifest）；
  * 传入 `fanoutTargets` 时只向目标集 fanout，并接受无签名的非 public manifest（信任边界 = 目标集 + 服务端 servicer）。
  * 非 public 命中默认写盘；public 按 `cache: true` 择新写盘。
- * 本地已验签公开缓存立即返回（`cache: true` 时后台 fanout 刷新）；非 public / 未验签 public 本地命中仅 targeted 模式返回，
- * public 模式拒绝。同 key（含规范化目标集）in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
- * @param {{ username: string, ownerEntityHash: string, logicalPath: string, fanoutTargets?: string[], cache?: boolean, timeoutMs?: number }} context - 拉取上下文
+ * 本地已验签公开缓存默认立即返回（`cache: true` 时后台 fanout 刷新）；`revalidate: true` 时改为阻塞等待本次 fanout 择新，
+ * 无新则回退本地。非 public / 未验签 public 本地命中仅 targeted 模式返回，public 模式拒绝。
+ * 同 key（含规范化目标集）in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
+ * @param {{ username: string, ownerEntityHash: string, logicalPath: string, fanoutTargets?: string[], cache?: boolean, revalidate?: boolean, timeoutMs?: number }} context - 拉取上下文
  * @returns {Promise<import('./normalize.mjs').FileManifest | null>} 校验后的 manifest，失败为 null
  */
 export async function fetchManifest(context) {
@@ -40,6 +41,7 @@ export async function fetchManifest(context) {
 	const logicalPath = context.logicalPath.replace(/^\/+/, '')
 	if (!ownerEntityHash || !logicalPath || !username) return null
 
+	const revalidate = context.revalidate === true
 	const timeoutMs = Number(context.timeoutMs) > 0
 		? Number(context.timeoutMs)
 		: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS
@@ -52,7 +54,7 @@ export async function fetchManifest(context) {
 	const localPromise = loadFileManifest(ownerEntityHash, logicalPath)
 	const shared = beginFedFanoutFetch({
 		inflight: manifestInflight,
-		inflightKey: `${username}\0${expectedKey}\0${targeted ? 'targeted' : 'public'}` + (fanoutTargets?.length ? `\0${fanoutTargets.join('\0')}` : ''),
+		inflightKeyBase: `${username}\0${expectedKey}`,
 		username,
 		action: 'fed_manifest_get',
 		/**
@@ -78,10 +80,18 @@ export async function fetchManifest(context) {
 	})
 	const local = await localPromise
 
-	// 本地已验签公开命中：立即返回；cache: true 时后台 fanout 择新刷新。
+	// 本地已验签公开命中：默认立即返回，cache: true 时后台 fanout 择新刷新；
+	// revalidate: true 时阻塞等待本次 fanout，取新择旧并写回，fanout 无新（含超时）则回退本地。
 	const isLocalPublic = local?.transferKeyDescriptor?.type === 'public' && !!local?.meta?.publicSig
 	if (isLocalPublic) {
-		if (wantCache && shared) void shared.then(async result => {
+		if (shared && revalidate) {
+			const result = await shared
+			if (result && shouldPreferIncomingPublicManifest(local, result)) {
+				if (wantCache) await cachePublicManifest(ownerEntityHash, logicalPath, result)
+				return result
+			}
+		}
+		else if (wantCache && shared) void shared.then(async result => {
 			if (result && shouldPreferIncomingPublicManifest(local, result))
 				await cachePublicManifest(ownerEntityHash, logicalPath, result)
 		})

package/node/entity_store.mjs

@@ -17,6 +17,7 @@ import { readJsonFile, writeJsonFile } from '../utils/json_io.mjs'
  * @property {(entityHash: string, logicalPath: string) => Promise<object | null>} readManifest
  * @property {(entityHash: string, logicalPath: string, data: object) => Promise<void>} writeManifest
  * @property {(entityHash: string, logicalPath: string) => Promise<boolean>} statManifest
+ * @property {(entityHash: string, logicalPath: string) => Promise<void>} [deleteManifest]
  * @property {() => Promise<string[]>} listEntityHashes
  */
 
@@ -210,5 +211,19 @@ export function createFsEntityStore(baseDir) {
 				return false
 			}
 		},
+
+		/**
+		 * @param {string} entityHash 128 位十六进制
+		 * @param {string} logicalPath EVFS 逻辑路径
+		 * @returns {Promise<void>} 删除 manifest（不存在视为成功）
+		 */
+		async deleteManifest(entityHash, logicalPath) {
+			try {
+				await fsp.unlink(manifestPath(entityHash, logicalPath))
+			}
+			catch (error) {
+				if (/** @type {NodeJS.ErrnoException} */ error.code !== 'ENOENT') throw error
+			}
+		},
 	}
 }

package/package.json

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