@steve02081504/fount-p2p 0.0.23 → 0.0.25

package/files/chunk/responder.mjs

@@ -0,0 +1,104 @@
+import { handleIncomingManifestGet } from '../manifest/fetch.mjs'
+import { resolvePendingManifestFetch } from '../manifest/pending.mjs'
+
+import { handleIncomingChunkGet } from './fetch.mjs'
+import { resolvePendingChunkFetch } from './pending.mjs'
+
+/**
+ * 群联邦 / TrustGraph 路径：响应带 requestId 的 fed_chunk_get。
+ * @param {object} data 入站 fed_chunk_get
+ * @param {string} peerId 对端 id
+ * @param {(resp: object, peerId: string) => void} sendChunkData 发送 fed_chunk_data
+ * @returns {Promise<void>}
+ */
+export async function handleFedChunkGetIngress(data, peerId, sendChunkData) {
+	await handleIncomingChunkGet(data, sendChunkData, peerId)
+}
+
+/**
+ * @param {object} data 入站 fed_chunk_data（含 requestId 时 resolve pending fetch）
+ * @returns {boolean} 是否命中 pending
+ */
+export function handleFedChunkDataIngress(data) {
+	return resolvePendingChunkFetch(data)
+}
+
+/**
+ * @param {object} data 入站 fed_manifest_get
+ * @param {string} peerId 对端 id
+ * @param {(resp: object, peerId: string) => void} sendManifestData 发送 fed_manifest_data
+ * @returns {Promise<void>}
+ */
+export async function handleFedManifestGetIngress(data, peerId, sendManifestData) {
+	await handleIncomingManifestGet(data, sendManifestData, peerId)
+}
+
+/**
+ * @param {object} data 入站 fed_manifest_data
+ * @returns {Promise<boolean>} 是否命中 pending
+ */
+export function handleFedManifestDataIngress(data) {
+	return resolvePendingManifestFetch(data)
+}
+
+/**
+ * @param {(resp: object, peerId: string) => void} sendData 发送
+ * @param {{ enqueue: (prio: number, cleanup: () => void) => void }} [fedOut] 出站限速队列
+ * @returns {(resp: object, peerId: string) => void} 可入队的发送
+ */
+function wrapSend(sendData, fedOut) {
+	if (!fedOut) return sendData
+	return (resp, peerId) => {
+		fedOut.enqueue(6, () => {
+			try { sendData(resp, peerId) }
+			catch { /* peer gone */ }
+		})
+	}
+}
+
+/**
+ * Trystero room：注册带 requestId 的 fed_chunk_* + fed_manifest_*（TrustGraph / 群全局 miss）。
+ * @param {object} room Trystero room
+ * @param {{ enqueue: (prio: number, cleanup: () => void) => void }} [fedOut] 出站队列
+ * @param {(roomKey: string, action: string, rtcLimits: object) => boolean} [guardGet] RTC 负载守卫
+ * @param {object} [rtcLimits] RTC 限额
+ * @param {string} [roomKey] 房间键
+ * @returns {void}
+ */
+export function attachTrustGraphFedChunkResponder(room, fedOut, guardGet, rtcLimits = {}, roomKey = '') {
+	const [sendChunkData, getChunkData] = room.makeAction('fed_chunk_data')
+	const [, getChunkGet] = room.makeAction('fed_chunk_get')
+	const [sendManifestData, getManifestData] = room.makeAction('fed_manifest_data')
+	const [, getManifestGet] = room.makeAction('fed_manifest_get')
+
+	const sendChunk = wrapSend((resp, peerId) => {
+		try { sendChunkData(resp, peerId) }
+		catch { /* peer gone */ }
+	}, fedOut)
+	const sendManifest = wrapSend((resp, peerId) => {
+		try { sendManifestData(resp, peerId) }
+		catch { /* peer gone */ }
+	}, fedOut)
+
+	getChunkGet((data, peerId) => {
+		if (guardGet && !guardGet(roomKey, 'fed_chunk_get', rtcLimits)) return
+		if (!data?.requestId) return
+		void handleFedChunkGetIngress(data, peerId, sendChunk)
+	})
+
+	getChunkData(data => {
+		if (!data?.requestId) return
+		handleFedChunkDataIngress(data)
+	})
+
+	getManifestGet((data, peerId) => {
+		if (guardGet && !guardGet(roomKey, 'fed_manifest_get', rtcLimits)) return
+		if (!data?.requestId) return
+		void handleFedManifestGetIngress(data, peerId, sendManifest)
+	})
+
+	getManifestData(data => {
+		if (!data?.requestId) return
+		handleFedManifestDataIngress(data)
+	})
+}

package/files/{chunk_store.mjs → chunk/store.mjs}

@@ -4,8 +4,8 @@ import fsp from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { pipeline } from 'node:stream/promises'
 
-import { isHex64 } from '../core/hexIds.mjs'
-import { getNodeDir } from '../node/instance.mjs'
+import { isHex64 } from '../../core/hexIds.mjs'
+import { getNodeDir } from '../../node/instance.mjs'
 
 /**
  * @returns {string} `{nodeDir}/chunks`

package/files/{chunk_fetch_verify.mjs → chunk/verify.mjs}

@@ -1,5 +1,5 @@
-import { isHex64 } from '../core/hexIds.mjs'
-import { sha256Hex } from '../crypto/crypto.mjs'
+import { isHex64 } from '../../core/hexIds.mjs'
+import { sha256Hex } from '../../crypto/crypto.mjs'
 
 /**
  * @param {string} chunkHash 期望的 64 hex 密文哈希

package/files/evfs.mjs

@@ -6,15 +6,15 @@ import { getEntityStore } from '../node/instance.mjs'
 
 import { buildFileManifestFromEnc, encryptPlaintextToMultiPartsAsync, encryptPlaintextToParts, manifestPartsForPersist } from './assemble.mjs'
 import { createManifestPlaintextStream, encryptReadableToParts } from './assemble_stream.mjs'
-import { fetchChunk } from './chunk_fetch.mjs'
-import { createChunkReadStream, getChunk, hasChunk, putChunk } from './chunk_store.mjs'
-import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
+import { fetchChunk } from './chunk/fetch.mjs'
+import { createChunkReadStream, getChunk, hasChunk, putChunk } from './chunk/store.mjs'
+import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest/normalize.mjs'
 import { assembleManifestPlaintext, resolveContentKey } from './transfer_key.mjs'
 import { readDagManifestPlaintext, resolveTransferKeyDependencies } from './transfer_key_registry.mjs'
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @returns {{ getGroupFileMasterKey?: Function, getVaultMasterKey?: Function }} 密钥依赖
  */
 function transferKeyDependenciesForReplica(replicaUsername, manifest) {
@@ -31,7 +31,7 @@ function transferKeyDependenciesForReplica(replicaUsername, manifest) {
 
 /**
  * @param {string} username 拉取身份
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {{ fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<boolean>} 全部 part 是否已就位
  */
@@ -53,15 +53,14 @@ async function ensureManifestPartsLocal(username, manifest, options = {}) {
 /**
  * @param {string} ownerEntityHash 所有者
  * @param {string} logicalPath 路径
- * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 归一化 manifest
+ * @returns {Promise<import('./manifest/normalize.mjs').FileManifest | null>} 本机已写盘的 manifest
  */
 export async function loadFileManifest(ownerEntityHash, logicalPath) {
-	const manifest = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
-	return manifest ? normalizeFileManifest(manifest) : null
+	return getEntityStore().readManifest(ownerEntityHash, logicalPath)
 }
 
 /**
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @returns {Promise<void>}
  */
 export async function saveFileManifest(manifest) {
@@ -69,7 +68,7 @@ export async function saveFileManifest(manifest) {
 }
 
 /**
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {Array<Buffer | Uint8Array>} partBytes 密文块
  * @returns {Promise<void>}
  */
@@ -80,7 +79,7 @@ export async function storeManifestParts(manifest, partBytes) {
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<Buffer | null>} 明文内容
  */
@@ -104,7 +103,7 @@ export async function readManifestPlaintext(replicaUsername, manifest, options =
 
 /**
  * @param {string} replicaUsername 副本用户名
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {{ username?: string, fetchChunk?: Function }} [options] miss 拉取
  * @returns {Promise<import('node:stream').Readable | null>} 明文流
  */
@@ -134,10 +133,10 @@ export async function readManifestPlaintextStream(replicaUsername, manifest, opt
  * @param {Buffer | Uint8Array} parameters.plaintext 明文
  * @param {string} [parameters.name] 文件名
  * @param {string} [parameters.mimeType] MIME
- * @param {import('./manifest.mjs').CeMode} [parameters.ceMode] 模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest/normalize.mjs').CeMode} [parameters.ceMode] 模式
+ * @param {import('./manifest/normalize.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
  * @param {object} [parameters.meta] meta
- * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
+ * @returns {Promise<import('./manifest/normalize.mjs').FileManifest>} 写入后的 manifest
  */
 export async function putFileManifest(parameters) {
 	const {
@@ -178,10 +177,10 @@ export async function putFileManifest(parameters) {
  * @param {number} parameters.plainSize 明文字节数
  * @param {string} [parameters.name] 文件名
  * @param {string} [parameters.mimeType] MIME
- * @param {import('./manifest.mjs').CeMode} [parameters.ceMode] 模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest/normalize.mjs').CeMode} [parameters.ceMode] 模式
+ * @param {import('./manifest/normalize.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
  * @param {object} [parameters.meta] meta
- * @returns {Promise<import('./manifest.mjs').FileManifest>} 写入后的 manifest
+ * @returns {Promise<import('./manifest/normalize.mjs').FileManifest>} 写入后的 manifest
  */
 export async function putFileManifestFromStream(parameters) {
 	const {
@@ -223,7 +222,7 @@ export async function putFileManifestFromStream(parameters) {
  * @returns {Promise<Buffer | null>} 明文或 null
  */
 export async function readPublicFile(replicaUsername, entityHash, logicalPath, options = {}) {
-	const { fetchPublicManifest } = await import('./manifest_fetch.mjs')
+	const { fetchPublicManifest } = await import('./manifest/fetch.mjs')
 	const manifest = await fetchPublicManifest({
 		username: options.username || replicaUsername,
 		ownerEntityHash: entityHash,

package/files/fed/fetch_shared.mjs

@@ -0,0 +1,39 @@
+import { randomUUID } from 'node:crypto'
+
+import { resolveNodeHash } from '../chunk/provider_registry.mjs'
+import { fanoutFedFetch } from '../fetch_fanout.mjs'
+
+/**
+ * inflight + pending wait + fanout 共用骨架。
+ * @template T
+ * @param {{
+ *   inflight: { acquire: (key: string, start: () => { done: Promise<T | null>, cancel: () => void }) => Promise<T | null> | null },
+ *   inflightKey: string,
+ *   username: string,
+ *   action: string,
+ *   registerWait: (requestId: string) => { done: Promise<T | null>, cancel: () => void },
+ *   buildPayload: (requestId: string, nodeHash: string) => object,
+ * }} options 选项
+ * @returns {Promise<T | null> | null} 共享 Promise；队满为 null
+ */
+export function beginFedFanoutFetch({
+	inflight,
+	inflightKey,
+	username,
+	action,
+	registerWait,
+	buildPayload,
+}) {
+	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))
+			}
+			catch { /* pending wait 超时/cancel 负责 settle */ }
+		})()
+		return { done: wait.done, cancel: wait.cancel }
+	})
+}

package/files/fed/responder.mjs

@@ -0,0 +1,47 @@
+import { subscribeWire } from '../../wire/subscribe.mjs'
+import { handleIncomingChunkGet } from '../chunk/fetch.mjs'
+import { resolvePendingChunkFetch } from '../chunk/pending.mjs'
+import { handleIncomingManifestGet } from '../manifest/fetch.mjs'
+import { resolvePendingManifestFetch } from '../manifest/pending.mjs'
+
+/** @typedef {import('../../wire/adapter.mjs').WireAdapter} WireAdapter */
+
+/**
+ * node scope wire：注册 fed_chunk_* + fed_manifest_*。
+ * @param {WireAdapter} wire action 表
+ * @returns {() => void} 取消挂载的 dispose
+ */
+export function attachNodeScopeFedResponder(wire) {
+	return subscribeWire(wire, {
+		/**
+		 * @param {unknown} data chunk 请求载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		fed_chunk_get(data, peerId) {
+			void handleIncomingChunkGet(data, (resp, pid) => {
+				try { wire.send('fed_chunk_data', resp, pid) }
+				catch { /* disconnected */ }
+			}, peerId)
+		},
+		/**
+		 * @param {unknown} data chunk 响应载荷
+		 */
+		fed_chunk_data(data) { resolvePendingChunkFetch(data) },
+		/**
+		 * @param {unknown} data manifest 请求载荷
+		 * @param {string} peerId 对端 nodeHash
+		 */
+		fed_manifest_get(data, peerId) {
+			void handleIncomingManifestGet(data, (resp, pid) => {
+				try { wire.send('fed_manifest_data', resp, pid) }
+				catch { /* disconnected */ }
+			}, peerId)
+		},
+		/**
+		 * @param {unknown} data manifest 响应载荷
+		 */
+		fed_manifest_data(data) {
+			void resolvePendingManifestFetch(data)
+		},
+	})
+}

package/files/{acl.mjs → manifest/acl.mjs}

@@ -1,12 +1,12 @@
-import { isLogicalEntityHash } from '../core/logical_entity.mjs'
-import { isWritableLocalEntity } from '../node/identity.mjs'
+import { isLogicalEntityHash } from '../../core/logical_entity.mjs'
+import { isWritableLocalEntity } from '../../node/identity.mjs'
 
-import { checkManifestAcl, resolveManifestAclType } from './manifest_acl_registry.mjs'
+import { checkManifestAcl, resolveManifestAclType } from './acl_registry.mjs'
 
 /**
  * @param {string} replicaUsername 请求 replica
  * @param {string} ownerEntityHash 文件 owner
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./normalize.mjs').FileManifest} manifest 清单
  * @returns {Promise<boolean>} 是否允许读
  */
 export async function canReadManifest(replicaUsername, ownerEntityHash, manifest) {

package/files/{manifest_acl_registry.mjs → manifest/acl_registry.mjs}

@@ -5,14 +5,14 @@
 /** @type {Map<string, { ownerId: string, handler: (context: ManifestAclContext, logicalPath?: string) => Promise<boolean> }>} */
 const handlersByType = new Map()
 
-/** @type {Map<string, { ownerId: string, match: (manifest: import('./manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
+/** @type {Map<string, { ownerId: string, match: (manifest: import('./normalize.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null }>} */
 const matchersByOwner = new Map()
 
 /**
  * @typedef {{
  *   replicaUsername: string,
  *   ownerEntityHash: string,
- *   manifest: import('./manifest.mjs').FileManifest,
+ *   manifest: import('./normalize.mjs').FileManifest,
  * }} ManifestAclContext
  */
 
@@ -23,12 +23,10 @@ const matchersByOwner = new Map()
  * @returns {void}
  */
 export function registerManifestAcl(type, ownerId, handler) {
-	const key = String(type)
-	const owner = String(ownerId)
-	const existing = handlersByType.get(key)
-	if (existing && existing.ownerId !== owner)
-		throw new Error(`manifest acl handler for '${key}' already registered by '${existing.ownerId}'`)
-	handlersByType.set(key, { ownerId: owner, handler })
+	const existing = handlersByType.get(type)
+	if (existing && existing.ownerId !== ownerId)
+		throw new Error(`manifest acl handler for '${type}' already registered by '${existing.ownerId}'`)
+	handlersByType.set(type, { ownerId, handler })
 }
 
 /**
@@ -37,20 +35,19 @@ export function registerManifestAcl(type, ownerId, handler) {
  * @returns {void}
  */
 export function unregisterManifestAcl(type, ownerId) {
-	const key = String(type)
-	const existing = handlersByType.get(key)
+	const existing = handlersByType.get(type)
 	if (!existing) return
-	if (existing.ownerId === String(ownerId))
-		handlersByType.delete(key)
+	if (existing.ownerId === ownerId)
+		handlersByType.delete(type)
 }
 
 /**
  * @param {string} ownerId 注册方
- * @param {(manifest: import('./manifest.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
+ * @param {(manifest: import('./normalize.mjs').FileManifest | null | undefined, ownerEntityHash: string) => string | null} match ACL 类型匹配
  * @returns {void}
  */
 export function registerManifestAclMatcher(ownerId, match) {
-	matchersByOwner.set(String(ownerId), { ownerId: String(ownerId), match })
+	matchersByOwner.set(ownerId, { ownerId, match })
 }
 
 /**
@@ -58,11 +55,11 @@ export function registerManifestAclMatcher(ownerId, match) {
  * @returns {void}
  */
 export function unregisterManifestAclMatcher(ownerId) {
-	matchersByOwner.delete(String(ownerId))
+	matchersByOwner.delete(ownerId)
 }
 
 /**
- * @param {import('./manifest.mjs').FileManifest | null | undefined} manifest manifest
+ * @param {import('./normalize.mjs').FileManifest | null | undefined} manifest manifest
  * @param {string} ownerEntityHash 所有者
  * @returns {string | null} ACL 类型
  */
@@ -81,7 +78,7 @@ export function resolveManifestAclType(manifest, ownerEntityHash) {
  * @returns {Promise<boolean>} 是否允许（未注册为 false）
  */
 export async function checkManifestAcl(type, context, logicalPath) {
-	const row = handlersByType.get(String(type))
+	const row = handlersByType.get(type)
 	if (!row?.handler) return false
 	return row.handler(context, logicalPath)
 }

package/files/{manifest_fetch.mjs → manifest/fetch.mjs}

@@ -1,20 +1,19 @@
-import { randomUUID } from 'node:crypto'
+import { parseEntityHash } from '../../core/entity_id.mjs'
+import { assertSafeEvfsLogicalPath } from '../../core/evfs_logical_path.mjs'
+import { isWritableLocalEntity } from '../../node/identity.mjs'
+import { getEntityStore } from '../../node/instance.mjs'
+import { ms } from '../../utils/duration.mjs'
+import { createInflightTable } from '../../utils/inflight_table.mjs'
+import { loadFileManifest, saveFileManifest } from '../evfs.mjs'
+import { beginFedFanoutFetch } from '../fed/fetch_shared.mjs'
 
+import { normalizeFileManifest } from './normalize.mjs'
 import {
 	manifestFetchExpectedKey,
 	MAX_PENDING_MANIFEST_FETCHES,
 	registerManifestFetchWait,
-} from '../federation/manifest_fetch_pending.mjs'
-import { isWritableLocalEntity } from '../node/identity.mjs'
-import { getEntityStore } from '../node/instance.mjs'
-import { ms } from '../utils/duration.mjs'
-import { createInflightTable } from '../utils/inflight_table.mjs'
-
-import { resolveNodeHash } from './chunk_provider_registry.mjs'
-import { loadFileManifest, saveFileManifest } from './evfs.mjs'
-import { fanoutFedFetch } from './fetch_fanout.mjs'
-import { normalizeFileManifest } from './manifest.mjs'
-import { shouldPreferIncomingPublicManifest } from './public_manifest.mjs'
+} from './pending.mjs'
+import { shouldPreferIncomingPublicManifest } from './public.mjs'
 
 const DEFAULT_MANIFEST_FETCH_TIMEOUT_MS = ms('8s')
 
@@ -29,7 +28,7 @@ const manifestInflight = createInflightTable({
  * 本地已有 publicSig 时立即返回，并后台 fanout；`cache: true` 时按 publishedAt 择新写盘。
  * 冷 miss 仍等 fanout。同 key in-flight 去重；调用方外层超时不 abort，后台继续填缓存。
  * @param {{ username: string, ownerEntityHash: string, logicalPath: string, cache?: boolean, timeoutMs?: number }} context - 拉取上下文
- * @returns {Promise<import('./manifest.mjs').FileManifest | null>} 验签后的 manifest，失败为 null
+ * @returns {Promise<import('./normalize.mjs').FileManifest | null>} 验签后的 manifest，失败为 null
  */
 export async function fetchPublicManifest(context) {
 	const ownerEntityHash = String(context.ownerEntityHash || '').trim().toLowerCase()
@@ -41,27 +40,31 @@ export async function fetchPublicManifest(context) {
 		? Number(context.timeoutMs)
 		: DEFAULT_MANIFEST_FETCH_TIMEOUT_MS
 	const expectedKey = manifestFetchExpectedKey(ownerEntityHash, logicalPath)
-	const inflightKey = `${username}\0${expectedKey}`
 	const wantCache = context.cache === true
 
 	// 先挂 in-flight（同步），再读本地 — 避免并发调用在 await 间隙各自 start
 	const localPromise = loadFileManifest(ownerEntityHash, logicalPath)
-	const shared = manifestInflight.acquire(inflightKey, () => {
-		const requestId = randomUUID()
-		const wait = registerManifestFetchWait(requestId, expectedKey, timeoutMs)
-		void (async () => {
-			try {
-				const { nodeHash } = await resolveNodeHash(username)
-				await fanoutFedFetch(username, 'fed_manifest_get', {
-					requestId,
-					nodeHash,
-					ownerEntityHash,
-					logicalPath,
-				})
-			}
-			catch { /* pending wait 超时/cancel 负责 settle */ }
-		})()
-		return { done: wait.done, cancel: wait.cancel }
+	const shared = beginFedFanoutFetch({
+		inflight: manifestInflight,
+		inflightKey: `${username}\0${expectedKey}`,
+		username,
+		action: 'fed_manifest_get',
+		/**
+		 * @param {string} requestId 请求 id
+		 * @returns {{ done: Promise<import('./normalize.mjs').FileManifest | null>, cancel: () => void }} 等待句柄
+		 */
+		registerWait: requestId => registerManifestFetchWait(requestId, expectedKey, timeoutMs),
+		/**
+		 * @param {string} requestId 请求 id
+		 * @param {string} nodeHash 目标节点 hash
+		 * @returns {object} fanout 载荷
+		 */
+		buildPayload: (requestId, nodeHash) => ({
+			requestId,
+			nodeHash,
+			ownerEntityHash,
+			logicalPath,
+		}),
 	})
 
 	const local = await localPromise
@@ -69,13 +72,12 @@ export async function fetchPublicManifest(context) {
 	if (!shared) return hasLocalPublic ? local : null
 
 	if (hasLocalPublic) {
-		// SWR：立刻回本地；后台 fanout 择新写盘（需 cache: true）
-		if (wantCache) {
+		if (wantCache) 
 			void shared.then(async result => {
 				if (result && shouldPreferIncomingPublicManifest(local, result))
 					await cachePublicManifest(ownerEntityHash, logicalPath, result)
 			})
-		}
+		
 		return local
 	}
 
@@ -89,41 +91,34 @@ export async function fetchPublicManifest(context) {
  * 将已验签公开 manifest 写入本地缓存（显式 apply；`fetchPublicManifest` 默认不调用）。
  * @param {string} ownerEntityHash owner
  * @param {string} logicalPath 路径
- * @param {import('./manifest.mjs').FileManifest} incoming 已验签入站清单
+ * @param {import('./normalize.mjs').FileManifest} incoming 已验签入站清单
  * @returns {Promise<void>}
  */
 export async function cachePublicManifest(ownerEntityHash, logicalPath, incoming) {
-	await maybeCacheIncomingPublicManifest(ownerEntityHash, logicalPath, incoming)
-}
-
-/**
- * @param {string} ownerEntityHash owner
- * @param {string} logicalPath 路径
- * @param {import('./manifest.mjs').FileManifest} incoming 已验签入站清单
- * @returns {Promise<void>}
- */
-async function maybeCacheIncomingPublicManifest(ownerEntityHash, logicalPath, incoming) {
 	if (isWritableLocalEntity(ownerEntityHash)) return
-	const store = getEntityStore()
-	const existing = await store.readManifest(ownerEntityHash, logicalPath)
+	const existing = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
 	if (existing && !shouldPreferIncomingPublicManifest(existing, incoming)) return
 	await saveFileManifest(incoming)
 }
 
 /**
  * 若本机有已签名公开 manifest 则响应 fed_manifest_get。
- * @param {string} username 用户
  * @param {object} payload 请求
  * @param {(response: object, peerId: string) => void} sendResponse 发送
  * @param {string} peerId 对端
  * @returns {Promise<void>}
  */
-export async function handleIncomingManifestGet(username, payload, sendResponse, peerId) {
-	void username
-	const ownerEntityHash = String(payload?.ownerEntityHash || '').trim().toLowerCase()
-	const logicalPath = String(payload?.logicalPath || '').trim().replace(/^\/+/, '')
+export async function handleIncomingManifestGet(payload, sendResponse, peerId) {
+	const parsedOwner = parseEntityHash(payload?.ownerEntityHash)
+	if (!parsedOwner) return
+	let logicalPath
+	try {
+		logicalPath = assertSafeEvfsLogicalPath(payload?.logicalPath)
+	}
+	catch { return }
 	const requestId = String(payload?.requestId || '')
-	if (!ownerEntityHash || !logicalPath || !requestId) return
+	if (!requestId) return
+	const { entityHash: ownerEntityHash } = parsedOwner
 
 	const raw = await getEntityStore().readManifest(ownerEntityHash, logicalPath)
 	const manifest = normalizeFileManifest(raw)

package/files/{manifest.mjs → manifest/normalize.mjs}

@@ -1,5 +1,5 @@
-import { isEntityHash128 } from '../core/entity_id.mjs'
-import { isHex64 } from '../core/hexIds.mjs'
+import { isEntityHash128 } from '../../core/entity_id.mjs'
+import { isHex64 } from '../../core/hexIds.mjs'
 
 /** @typedef {'plain' | 'convergent' | 'random'} CeMode */
 

package/files/manifest/pending.mjs

@@ -0,0 +1,53 @@
+import { compositeKey } from '../../core/composite_key.mjs'
+import { createFetchWaitTable } from '../../utils/fetch_wait.mjs'
+
+import { verifySignedPublicManifest } from './public.mjs'
+
+/** 并发 pending manifest fetch 上限。 */
+export const MAX_PENDING_MANIFEST_FETCHES = 512
+
+const table = createFetchWaitTable({ maxSize: MAX_PENDING_MANIFEST_FETCHES })
+
+/** @type {typeof table.pending} */
+export const pendingManifestFetches = table.pending
+
+/**
+ * @param {string} ownerEntityHash owner
+ * @param {string} logicalPath 路径
+ * @returns {string} 期望键
+ */
+export function manifestFetchExpectedKey(ownerEntityHash, logicalPath) {
+	return compositeKey(
+		String(ownerEntityHash || '').trim().toLowerCase(),
+		String(logicalPath || '').trim().replace(/^\/+/, ''),
+	)
+}
+
+/**
+ * @param {string} key requestId
+ * @param {string} expectedKey owner+path 复合键
+ * @param {number} timeoutMs 超时毫秒
+ * @returns {{ done: Promise<object | null>, cancel: () => void }} 等待 Promise 与取消
+ */
+export function registerManifestFetchWait(key, expectedKey, timeoutMs) {
+	return table.register(key, expectedKey, timeoutMs)
+}
+
+/**
+ * 处理 fed_manifest_data：验签通过后 resolve pending。
+ * @param {object} payload 入站载荷
+ * @returns {Promise<boolean>} 是否命中并完成等待
+ */
+export async function resolvePendingManifestFetch(payload) {
+	const requestId = String(payload?.requestId || '')
+	if (!requestId) return false
+	const entry = table.peek(requestId)
+	if (!entry) return false
+
+	const verified = await verifySignedPublicManifest(payload?.manifest)
+	if (!verified) return false
+	const key = manifestFetchExpectedKey(verified.ownerEntityHash, verified.logicalPath)
+	if (key !== entry.expectedKey) return false
+
+	return table.settle(requestId, verified)
+}