@steve02081504/fount-p2p 0.0.23 → 0.0.24

package/README.md

@@ -21,20 +21,20 @@ Requires **Node.js ≥ 20** (ESM + `import ... with { type: 'json' }`).
 import {
  startNode,
  ensureUserRoom,
- attachUserRoomDefaultWires,
+ attachNodeScopeDefaultFeatures,
  createScopedLinkRoom,
 } from '@steve02081504/fount-p2p'
 
 await startNode({ nodeDir: '/path/to/p2p/node' })
 await ensureUserRoom() // slot + runtime only
-attachUserRoomDefaultWires({ replicaUsername: 'alice' }) // full business wires
+attachNodeScopeDefaultFeatures({ replicaUsername: 'alice' }) // full business wires
 ```
 
 Shells talk to the **fount network** (`ensureLinkToNode` / `sendToNodeLink` / rooms). Do not import `link/providers/*` or choose WebRTC / BLE / LAN / Nostr yourself. Provider registration: `registerLinkProvider` from `@steve02081504/fount-p2p/link` or the facade.
 
 Dial order is descending link **`level`**: `lan_tcp` → `webrtc` → `ble_gatt` → `nostr` (−∞ last resort). Discovery **`priority`** only orders handshake / presence media. Details: [docs/transports.md](./docs/transports.md).
 
-Public transport subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope`, `room_scopes`, `remote_user_room`. Other `transport/*` modules are internal.
+Public transport subpaths: `link_registry`, `user_room`, `group_link_set`, `node_scope`, `room_scopes`, `remote_user_room`, `scoped_link`. Other `transport/*` modules are internal.
 
 ## Infra relay (optional)
 
@@ -73,7 +73,7 @@ Reputation pull/apply is separate: `pullReputationFromNode` → JSON; `setReputa
 | L0 | `core/` | Pure primitives: `hexIds`, `entity_id*`, `canonical_json` |
 | L1 | `crypto/`, `wire/`, `schemas/` | Cryptography, wire protocol, canonical validation |
 | L2 | `node/` | Node runtime: `identity`, `entity_store`, `denylist`, `reputation_store` |
-| L3 | `discovery/`, `link/`, `transport/`, `rooms/` | Discovery + fount-network registry/rooms (`./link` = provider registration only) |
+| L3 | `discovery/`, `link/`, `transport/` | Discovery + fount-network registry/rooms (`./link` = provider registration only) |
 | L4 | `trust_graph/`, `mailbox/`, `dag/`, `federation/`, `files/`, `governance/`, `reputation/` | Federation, store-and-forward, DAG, EVFS, tunables |
 | — | `infra/` | Optional public-good relay (`startInfra` / CLI) |
 | — | `registries/` | Pluggable registries (event type, part path, room provider, …) |
@@ -85,10 +85,10 @@ Facade entry: `index.mjs` (`startNode`, `createGroupLinkSet`, `registerDiscovery
 | Module | Role |
 |---|---|
 | `link_registry.mjs` | fount-network facade: dial fallback, scope/overlay |
-| `user_room.mjs` / `group_link_set.mjs` / `node_scope.mjs` | rooms + composable node-scope wires |
+| `user_room.mjs` / `group_link_set.mjs` / `node_scope/` | rooms + composable node-scope wires |
 | `room_scopes.mjs` / `remote_user_room.mjs` | scope constants / remote user slot |
 
-`runtime_bootstrap`, `offer_answer`, `advert_ingest` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by discovery `nostr.mjs` / `adverts.mjs`; not a package export). The Nostr **link** provider (`link/providers/nostr.mjs`) reuses the same discovery signal path (`type: 'link'`) as a last-resort duplex pipe. `ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. `setSignalingRuntimeConfig` → `reloadDiscoveryRelays`. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
+`runtime_bootstrap`, `offer_answer` are **internal** (transport). Signal crypto / rendezvous live under `discovery/internal/signal_crypto.mjs` (used by discovery `nostr.mjs` / `adverts.mjs`; not a package export). The Nostr **link** provider (`link/providers/nostr.mjs`) reuses the same discovery signal path (`type: 'link'`) as a last-resort duplex pipe. `ensureRuntime` returns after registration and scheduling warm-up; it does not await lan_tcp listen, public relays, or Bluetooth. `setSignalingRuntimeConfig` → `reloadDiscoveryRelays`. See [docs/runtime.md](./docs/runtime.md) and [docs/transports.md](./docs/transports.md).
 
 Root contains only the facade and package metadata; all modules live in layered subdirectories.
 
@@ -121,3 +121,5 @@ Group chunk remote storage (S3, etc.) is implemented by the shell as `GroupStora
 - Signaling and WebRTC glare: [`docs/signaling.md`](./docs/signaling.md)
 - Runtime bootstrap / BT probe: [`docs/runtime.md`](./docs/runtime.md)
 - Infra relay / node-scope attaches: [`docs/infra.md`](./docs/infra.md)
+- Wire part / fanout attaches: [`docs/wire.md`](./docs/wire.md)
+- EVFS public manifests / fetch: [`docs/evfs.md`](./docs/evfs.md)

package/core/object.mjs

@@ -0,0 +1,9 @@
+/**
+ * 判定 `{}` 形态对象（原型为 Object.prototype）。
+ * 数组、Date/Map/类实例、null 原型对象一律否。
+ * @param {unknown} value 待判定值
+ * @returns {value is Record<string, unknown>} 是否为普通对象
+ */
+export function isPlainObject(value) {
+	return value != null && Object.getPrototypeOf(value) === Object.prototype
+}

package/core/partpath.mjs

@@ -0,0 +1,10 @@
+const PARTPATH_RE = /^[\w-]+(?:\/[\w-]+)*$/
+
+/**
+ * 入站 partpath 形校验（不改写）。仅用于非本机网络边界。
+ * @param {unknown} value 原始 partpath
+ * @returns {string | null} 合法则原样返回；否则 null
+ */
+export function parsePartpath(value) {
+	return typeof value === 'string' && PARTPATH_RE.test(value) ? value : null
+}

package/dag/storage.mjs

@@ -9,11 +9,6 @@ import { pipeline } from 'node:stream/promises'
 import { withAsyncMutex } from '../utils/async_mutex.mjs'
 import { atomicTemporaryPath, finalizeAtomicRename } from '../utils/atomic_fs.mjs'
 
-/**
- * 原子重命名 finalize（re-export）。
- */
-export { finalizeAtomicRename } from '../utils/atomic_fs.mjs'
-
 /** 流式重写 JSONL 时分块写入的行数上限 */
 const WRITE_JSONL_CHUNK_LINES = 1000
 

package/dag/strip_extensions.mjs

@@ -1,17 +1,15 @@
 /**
  * DAG 事件行读盘时剥离的本地扩展键（不得进入验签域 / 联邦 wire）。
  */
-import { isPlainObject } from '../wire/ingress.mjs'
 
 /** 落盘后 trusted 读路径仍须剥除的 sidecar 键。 */
 export const DAG_EVENT_LOCAL_EXTENSION_KEYS = new Set(['receivedAt', 'isRemote'])
 
 /**
- * @param {unknown} row JSONL 行
+ * @param {object} row JSONL 行
  * @returns {object} 剥离扩展键后的副本
  */
 export function stripDagEventLocalExtensions(row) {
-	if (!isPlainObject(row)) return row
 	const out = { ...row }
 	for (const key of DAG_EVENT_LOCAL_EXTENSION_KEYS) delete out[key]
 	return out

package/{wire/part_query_cache.mjs → federation/part_query/cache.mjs}

@@ -1,8 +1,7 @@
-import { sha256Hex } from '../crypto/crypto.mjs'
-import { normalizePartQueryCacheMaterial } from '../schemas/part_query.mjs'
-import { createLruMap } from '../utils/lru.mjs'
-
-import partQueryTunables from './part_query.tunables.json' with { type: 'json' }
+import { sha256Hex } from '../../crypto/crypto.mjs'
+import { normalizePartQueryCacheMaterial } from '../../schemas/part_query.mjs'
+import partQueryTunables from '../../schemas/part_query.tunables.json' with { type: 'json' }
+import { createLruMap } from '../../utils/lru.mjs'
 
 /**
  * @typedef {{ rows: unknown[], storedAt: number }} PartQueryCacheEntry
@@ -71,13 +70,14 @@ export function createPartQueryCache(options = {}) {
 		 * @param {string} partpath part 路径
 		 * @param {string} kind 查询标签
 		 * @param {unknown} query 查询体
-		 * @param {unknown[]} rows 聚合 rows
+		 * @param {unknown[]} rows 聚合 rows（空数组不入库）
 		 * @param {number} [now=Date.now()] 当前时间
 		 * @returns {void}
 		 */
 		set(partpath, kind, query, rows, now = Date.now()) {
 			const key = partQueryCacheKey(partpath, kind, query)
-			if (!key || !rows) return
+			// 空 miss 不缓存：mesh 晚就绪 / 超时早查询不应被长 TTL 负缓存粘住
+			if (!key || !Array.isArray(rows) || rows.length === 0) return
 			sweep(now)
 			map.touch(key, {
 				rows: rows.slice(0, maxHits),

package/{wire/part_query.mjs → federation/part_query/runtime.mjs}

@@ -1,29 +1,27 @@
 import { randomUUID } from 'node:crypto'
 
-import { createDedupeSlot } from '../federation/dedupe_slot.mjs'
-import { getNodeHash } from '../node/identity.mjs'
-import { loadReputation } from '../node/reputation_store.mjs'
-import { isQuarantinedPure } from '../reputation/engine.mjs'
+import { compositeKey } from '../../core/composite_key.mjs'
+import { getNodeHash } from '../../node/identity.mjs'
+import { loadReputation } from '../../node/reputation_store.mjs'
+import { isQuarantinedPure } from '../../reputation/engine.mjs'
 import {
 	clampPartQueryRows,
 	parsePartQueryReq,
-	parsePartQueryRes,
-} from '../schemas/part_query.mjs'
-import { sendToNodeLink } from '../transport/link_registry.mjs'
-import { buildMergedGraph } from '../trust_graph/build.mjs'
-import { pickTopFromGraph } from '../trust_graph/engine.mjs'
-import { resolveFederationFanoutTopK } from '../trust_graph/resolve.mjs'
-import trustGraphTunables from '../trust_graph/tunables.json' with { type: 'json' }
-
-import { isPlainObject } from './ingress.mjs'
-import partQueryTunables from './part_query.tunables.json' with { type: 'json' }
-import { createPartQueryCache, partQueryCache } from './part_query_cache.mjs'
-import { consumeWireRateBucket } from './rate_bucket.mjs'
-import { finishMultiWireWaiters, registerMultiWireWait } from './wait.mjs'
-
-/** @typedef {import('../schemas/part_query.mjs').PartQueryReq} PartQueryReq */
-/** @typedef {import('../schemas/part_query.mjs').PartQueryRes} PartQueryRes */
-/** @typedef {import('./part_ingress.mjs').PartWireAdapter} PartWireAdapter */
+} from '../../schemas/part_query.mjs'
+import partQueryTunables from '../../schemas/part_query.tunables.json' with { type: 'json' }
+import { buildMergedGraph } from '../../trust_graph/build.mjs'
+import { pickTopFromGraph } from '../../trust_graph/engine.mjs'
+import { resolveFederationFanoutTopK } from '../../trust_graph/resolve.mjs'
+import trustGraphTunables from '../../trust_graph/tunables.json' with { type: 'json' }
+import { finishMultiWireWaiters, registerMultiWireWait } from '../../wire/wait.mjs'
+import { createDedupeSlot } from '../dedupe_slot.mjs'
+
+import { createPartQueryCache, partQueryCache } from './cache.mjs'
+
+/** @typedef {import('../../schemas/part_query.mjs').PartQueryReq} PartQueryReq */
+/** @typedef {import('../../schemas/part_query.mjs').PartQueryRes} PartQueryRes */
+
+/** @typedef {import('../../wire/adapter.mjs').WireAdapter} PartQueryWire */
 
 /**
  * @typedef {{
@@ -41,7 +39,7 @@ import { finishMultiWireWaiters, registerMultiWireWait } from './wait.mjs'
  * @typedef {{
  *   takeDedupe: (key: string) => boolean
  *   relayPending: Map<string, RelayPending>
- *   originWaits: Map<string, Map<string, import('./wait.mjs').WireWaiter[]>>
+ *   originWaits: Map<string, Map<string, import('../../wire/wait.mjs').WireWaiter[]>>
  *   originBags: Map<string, { rows: unknown[], maxHits: number, expected: number, received: number, respondedPeers: Set<string>, rowKey?: (row: unknown) => string }>
  *   cache: ReturnType<typeof createPartQueryCache>
  *   handlers: Map<string, QueryInboundHandler>
@@ -61,7 +59,7 @@ import { finishMultiWireWaiters, registerMultiWireWait } from './wait.mjs'
 /**
  * @typedef {{
  *   upstreamPeerId: string
- *   wire: PartWireAdapter
+ *   wire: PartQueryWire
  *   request: PartQueryReq
  *   localRows: unknown[]
  *   remoteRows: unknown[]
@@ -100,7 +98,7 @@ const defaultState = createPartQueryNodeState({ cache: partQueryCache })
  * @param {PartQueryDependencies} [dependencies] 依赖
  * @returns {PartQueryNodeState} 节点状态
  */
-function resolveState(dependencies = {}) {
+export function resolvePartQueryState(dependencies = {}) {
 	return dependencies.state || defaultState
 }
 
@@ -110,7 +108,7 @@ function resolveState(dependencies = {}) {
  * @returns {string} handler 键
  */
 function handlerKey(partpath, kind) {
-	return `${partpath}\0${kind}`
+	return compositeKey(partpath, kind)
 }
 
 /**
@@ -122,7 +120,7 @@ function handlerKey(partpath, kind) {
  * @returns {void}
  */
 export function registerQueryInboundHandler(partpath, kind, handler, state = defaultState) {
-	state.handlers.set(handlerKey(String(partpath || '').trim(), String(kind || '').trim()), handler)
+	state.handlers.set(handlerKey(partpath, kind), handler)
 }
 
 /**
@@ -202,17 +200,15 @@ async function selectQueryNeighbors(username, exclude, dependencies) {
 }
 
 /**
- * @param {string} username 用户
  * @param {string} nodeHash 目标
  * @param {string} action action 名
  * @param {unknown} payload 载荷
  * @param {PartQueryDependencies} dependencies 依赖
  * @returns {Promise<boolean>} 是否发出
  */
-async function deliverQuery(username, nodeHash, action, payload, dependencies) {
-	void username
-	if (dependencies.deliver) return Boolean(await dependencies.deliver(nodeHash, action, payload))
-	return sendToNodeLink(nodeHash, { scope: 'node', action, payload })
+async function deliverQuery(nodeHash, action, payload, dependencies) {
+	if (!dependencies.deliver) return false
+	return Boolean(await dependencies.deliver(nodeHash, action, payload))
 }
 
 /**
@@ -254,14 +250,14 @@ function flushRelayPending(pending) {
 
 /**
  * @param {{ replicaUsername?: string }} wireContext attach 上下文
- * @param {PartWireAdapter} wire wire
+ * @param {PartQueryWire} wire wire
  * @param {PartQueryReq} request 已校验请求
  * @param {string} peerId 来路
  * @param {PartQueryDependencies} dependencies 依赖
  * @returns {Promise<void>}
  */
-async function processIncomingRequest(wireContext, wire, request, peerId, dependencies) {
-	const state = resolveState(dependencies)
+export async function processIncomingPartQueryRequest(wireContext, wire, request, peerId, dependencies) {
+	const state = resolvePartQueryState(dependencies)
 	const nodeHashOf = dependencies.getNodeHash || getNodeHash
 	const now = dependencies.now || Date.now
 	const username = String(wireContext.replicaUsername || '')
@@ -311,7 +307,7 @@ async function processIncomingRequest(wireContext, wire, request, peerId, depend
 
 	let sent = 0
 	for (const target of neighbors)
-		if (await deliverQuery(username, target, 'part_query_req', forwardPayload, dependencies)) sent++
+		if (await deliverQuery(target, 'part_query_req', forwardPayload, dependencies)) sent++
 	pending.expected = sent
 
 	if (sent === 0 || pending.received >= pending.expected) {
@@ -322,39 +318,6 @@ async function processIncomingRequest(wireContext, wire, request, peerId, depend
 	pending.timer = setTimeout(() => flushRelayPending(pending), resolvePartQueryHopTimeoutMs(request.ttl))
 }
 
-/**
- * 挂载 part_query_req / part_query_res。
- * @param {{ replicaUsername?: string }} wireContext 入站上下文
- * @param {PartWireAdapter} wire wire
- * @param {PartQueryDependencies} [dependencies] 可注入依赖（含 per-node state）
- * @returns {() => void} 取消挂载的 dispose
- */
-export function attachPartQueryWire(wireContext, wire, dependencies = {}) {
-	const state = resolveState(dependencies)
-	const offs = [
-		wire.on('part_query_req', (data, peerId) => {
-			if (!isPlainObject(data)) return
-			const request = parsePartQueryReq(data)
-			if (!request) return
-			if (!state.takeDedupe(request.requestId)) return
-			const source = String(peerId || request.originNodeHash || '').trim().toLowerCase()
-			if (source && !consumeWireRateBucket(`part_query:${source}`, {
-				maxCount: partQueryTunables.ratePerSourcePerMin,
-			})) return
-			void processIncomingRequest(wireContext, wire, request, String(peerId || ''), dependencies)
-		}),
-		wire.on('part_query_res', (data, peerId) => {
-			const response = parsePartQueryRes(data)
-			if (!response) return
-			handleIncomingPartQueryResponse(response, String(peerId || ''), dependencies)
-		}),
-	]
-	return () => {
-		for (const off of offs)
-			try { off?.() } catch { /* ignore */ }
-	}
-}
-
 /**
  * @param {PartQueryRes} response 响应
  * @param {string} peerId 来路
@@ -362,8 +325,7 @@ export function attachPartQueryWire(wireContext, wire, dependencies = {}) {
  * @returns {void}
  */
 export function handleIncomingPartQueryResponse(response, peerId = '', dependencies = {}) {
-	const state = resolveState(dependencies)
-	// 同一 peer 只计一次，防重复回包灌水/提早凑齐 expected
+	const state = resolvePartQueryState(dependencies)
 	const responderKey = String(peerId || response.fromNodeHash || '').trim().toLowerCase()
 	const relay = state.relayPending.get(response.requestId)
 	if (relay) {
@@ -405,7 +367,7 @@ export function handleIncomingPartQueryResponse(response, peerId = '', dependenc
  * @returns {Promise<unknown[]>} 合并后的 rows
  */
 export async function queryNetwork(username, partpath, kind, query, options = {}) {
-	const state = resolveState(options)
+	const state = resolvePartQueryState(options)
 	const now = options.now || Date.now
 	const nodeHashOf = options.getNodeHash || getNodeHash
 
@@ -420,7 +382,6 @@ export async function queryNetwork(username, partpath, kind, query, options = {}
 		partQueryTunables.maxHits,
 		Math.max(1, Math.floor(Number(options.maxHits ?? options.budget?.maxHits) || partQueryTunables.maxHits)),
 	)
-	// 第一跳中继等待 hopTimeout(ttl) 才 flush，发起端默认取 ttl+1 档以免先行超时
 	const timeoutMs = Math.max(
 		1,
 		Math.floor(Number(options.timeoutMs) || resolvePartQueryHopTimeoutMs(ttl + 1)),
@@ -435,8 +396,8 @@ export async function queryNetwork(username, partpath, kind, query, options = {}
 	const request = {
 		requestId: randomUUID(),
 		originNodeHash: nodeHashOf(),
-		partpath: String(partpath || '').trim(),
-		kind: String(kind || '').trim(),
+		partpath,
+		kind,
 		query,
 		ttl,
 		budget: { maxHits },
@@ -444,7 +405,6 @@ export async function queryNetwork(username, partpath, kind, query, options = {}
 	const parsed = parsePartQueryReq(request)
 	if (!parsed) return mergeQueryRows([localRows], maxHits, options.rowKey)
 
-	// 预占 dedupe：若查询绕环回流到本机，入站侧直接丢弃
 	state.takeDedupe(parsed.requestId)
 
 	const bag = {
@@ -463,10 +423,9 @@ export async function queryNetwork(username, partpath, kind, query, options = {}
 	const neighbors = await selectQueryNeighbors(username, exclude, options)
 	let sent = 0
 	for (const target of neighbors)
-		if (await deliverQuery(username, target, 'part_query_req', parsed, options)) sent++
+		if (await deliverQuery(target, 'part_query_req', parsed, options)) sent++
 	bag.expected = sent
 
-	// deliver 可能同步回流；在赋值 expected 后再检查是否已齐
 	if (sent === 0 || bag.received >= bag.expected)
 		finishMultiWireWaiters(state.originWaits, parsed.requestId, '')
 	await waitPromise

package/files/assemble.mjs

@@ -10,7 +10,7 @@ import {
 	wrapContentKey,
 } from '../crypto/key.mjs'
 
-import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest.mjs'
+import { normalizeFileManifest, publicTransferKeyDescriptor } from './manifest/normalize.mjs'
 
 /** @type {Record<string, (plain: Buffer) => { contentHash: string, ciphertextHash: string, raw: Buffer, contentKey?: Buffer }>} */
 const ENCRYPTION_STRATEGIES = {
@@ -35,8 +35,8 @@ const ENCRYPTION_STRATEGIES = {
 }
 
 /**
- * @typedef {import('./manifest.mjs').FileManifest} FileManifest
- * @typedef {import('./manifest.mjs').CeMode} CeMode
+ * @typedef {import('./manifest/normalize.mjs').FileManifest} FileManifest
+ * @typedef {import('./manifest/normalize.mjs').CeMode} CeMode
  */
 
 /**
@@ -154,7 +154,7 @@ export async function encryptPlaintextToMultiPartsAsync(plaintext, ceMode = 'con
  * @param {string} [parameters.name] 文件名
  * @param {string} [parameters.mimeType] MIME
  * @param {CeMode} [parameters.ceMode] 加密模式
- * @param {import('./manifest.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
+ * @param {import('./manifest/normalize.mjs').TransferKeyDescriptor} [parameters.transferKeyDescriptor] 传递密钥
  * @param {object} [parameters.meta] 元数据
  * @returns {FileManifest} manifest（未写盘）
  */
@@ -224,7 +224,7 @@ export function buildFileManifestFromEnc(parameters, enc) {
  * @param {string} fileId 文件 ID
  * @param {Buffer} contentKey 随机密钥
  * @param {Buffer | string} H vault H
- * @returns {import('./manifest.mjs').TransferKeyDescriptor} 传输密钥描述
+ * @returns {import('./manifest/normalize.mjs').TransferKeyDescriptor} 传输密钥描述
  */
 export function vaultWrapDescriptor(entityHash, fileId, contentKey, H) {
 	return {

package/files/assemble_stream.mjs

@@ -8,7 +8,7 @@ import { encryptSliceToPart } from './assemble.mjs'
 import { decryptPart } from './transfer_key.mjs'
 
 /**
- * @typedef {import('./manifest.mjs').CeMode} CeMode
+ * @typedef {import('./manifest/normalize.mjs').CeMode} CeMode
  * @typedef {{ hash: string, size: number, raw: Buffer, contentHash?: string }} EncryptedPart
  */
 
@@ -113,7 +113,7 @@ function readStreamChunk(stream) {
 
 /**
  * 将 manifest 各密文块按 part.size 拼齐后解密，串联为明文可读流。
- * @param {import('./manifest.mjs').FileManifest} manifest 清单
+ * @param {import('./manifest/normalize.mjs').FileManifest} manifest 清单
  * @param {import('node:stream').Readable[]} partStreams 按序密文流
  * @param {Buffer | null} contentKey 随机密钥
  * @returns {Readable} 明文流

package/files/chunk/fetch.mjs

@@ -0,0 +1,101 @@
+import { bytesToBase64 } from '../../core/bytes_codec.mjs'
+import { assertHex64 } from '../../core/hexIds.mjs'
+import { ms } from '../../utils/duration.mjs'
+import { createInflightTable } from '../../utils/inflight_table.mjs'
+import { beginFedFanoutFetch } from '../fed/fetch_shared.mjs'
+
+import {
+	MAX_PENDING_CHUNK_FETCHES,
+	registerChunkFetchWait,
+} from './pending.mjs'
+import { fetchFederationChunk } from './provider_registry.mjs'
+import { getChunk, hasChunk, putChunk } from './store.mjs'
+import { verifiedChunkBytes } from './verify.mjs'
+
+const DEFAULT_CHUNK_FETCH_TIMEOUT_MS = ms('8s')
+
+/** 同 username+hash 共享一次 fanout；队满只丢已超基础超时的队首。 */
+const chunkInflight = createInflightTable({
+	maxSize: MAX_PENDING_CHUNK_FETCHES,
+	baseTimeoutMs: DEFAULT_CHUNK_FETCH_TIMEOUT_MS,
+})
+
+/**
+ * @typedef {{
+ *   username: string,
+ *   ciphertextHash: string,
+ *   ownerEntityHash?: string,
+ *   groupId?: string,
+ * }} FetchChunkContext
+ */
+
+/**
+ * @param {FetchChunkContext} context 上下文
+ * @returns {Promise<Uint8Array | null>} 密文块
+ */
+export async function fetchChunk(context) {
+	const hash = String(context.ciphertextHash || '').trim().toLowerCase()
+	const { username } = context
+	if (!hash || !username) return null
+
+	if (await hasChunk(hash))
+		return new Uint8Array(await getChunk(hash))
+
+	if (context.groupId) {
+		const verified = verifiedChunkBytes(hash, await fetchFederationChunk(username, context.groupId, hash))
+		if (verified) {
+			await putChunk(hash, verified)
+			return verified
+		}
+	}
+
+	const shared = beginFedFanoutFetch({
+		inflight: chunkInflight,
+		inflightKey: `${username}\0${hash}`,
+		username,
+		action: 'fed_chunk_get',
+		/**
+		 * @param {string} requestId 请求 id
+		 * @returns {{ done: Promise<Uint8Array | null>, cancel: () => void }} 等待句柄
+		 */
+		registerWait: requestId => registerChunkFetchWait(requestId, hash, DEFAULT_CHUNK_FETCH_TIMEOUT_MS),
+		/**
+		 * @param {string} requestId 请求 id
+		 * @param {string} nodeHash 目标节点 hash
+		 * @returns {object} fanout 载荷
+		 */
+		buildPayload: (requestId, nodeHash) => ({
+			requestId,
+			nodeHash,
+			chunkHash: hash,
+			ownerEntityHash: context.ownerEntityHash,
+		}),
+	})
+	if (!shared) return null
+
+	const verified = verifiedChunkBytes(hash, await shared)
+	if (verified) {
+		await putChunk(hash, verified)
+		return verified
+	}
+	return null
+}
+
+/**
+ * 若本机有 chunk 则响应 fed_chunk_get。
+ * @param {object} payload 请求
+ * @param {(response: object, peerId: string) => void} sendResponse 发送
+ * @param {string} peerId 对端
+ * @returns {Promise<void>}
+ */
+export async function handleIncomingChunkGet(payload, sendResponse, peerId) {
+	let hash
+	try {
+		hash = assertHex64(payload?.chunkHash, 'chunkHash')
+	}
+	catch { return }
+	if (!await hasChunk(hash)) return
+	const chunkBytes = await getChunk(hash)
+	if (!chunkBytes?.length) return
+	sendResponse({ requestId: payload.requestId, dataBase64: bytesToBase64(chunkBytes) }, peerId)
+}

package/files/chunk/pending.mjs

@@ -0,0 +1,59 @@
+import { base64ToBytes } from '../../core/bytes_codec.mjs'
+import { createFetchWaitTable } from '../../utils/fetch_wait.mjs'
+
+import { verifiedChunkBytes } from './verify.mjs'
+
+/** 并发 pending chunk fetch 上限。 */
+export const MAX_PENDING_CHUNK_FETCHES = 2048
+
+const table = createFetchWaitTable({ maxSize: MAX_PENDING_CHUNK_FETCHES })
+
+/** @type {typeof table.pending} */
+export const pendingChunkFetches = table.pending
+
+/**
+ * 注册 chunk 拉取等待槽（requestId 或 compositeKey）。
+ * @param {string} key 唯一等待键
+ * @param {string} expectedHash 期望 64 hex 密文哈希
+ * @param {number} timeoutMs 超时毫秒
+ * @param {{ rejectOnTimeout?: boolean }} [options] rejectOnTimeout 时 Promise 以 Error 拒绝
+ * @returns {{ done: Promise<Uint8Array | null>, cancel: () => void }} 等待 Promise 与取消函数
+ */
+export function registerChunkFetchWait(key, expectedHash, timeoutMs, options = {}) {
+	return table.register(key, expectedHash, timeoutMs, options)
+}
+
+/**
+ * 按等待键解析入站 chunk 响应（校验哈希后 resolve）。
+ * @param {string} key 等待键
+ * @param {string} expectedHash 期望哈希
+ * @param {Uint8Array | null} bytes 密文块
+ * @returns {boolean} 是否命中并完成等待
+ */
+export function resolveChunkFetchWait(key, expectedHash, bytes) {
+	const entry = table.peek(key)
+	if (!entry || entry.expectedKey !== expectedHash) return false
+	const verified = bytes ? verifiedChunkBytes(expectedHash, bytes) : null
+	if (bytes && !verified) return false
+	return table.settle(key, verified)
+}
+
+/**
+ * 处理 fed_chunk_data / 带 requestId 的响应载荷。
+ * @param {object} payload 入站载荷
+ * @returns {boolean} 是否命中 pending
+ */
+export function resolvePendingChunkFetch(payload) {
+	const requestId = typeof payload?.requestId === 'string' ? payload.requestId : ''
+	if (!requestId) return false
+	const entry = table.peek(requestId)
+	if (!entry) return false
+	if (typeof payload?.dataBase64 === 'string') {
+		try {
+			return resolveChunkFetchWait(requestId, entry.expectedKey, base64ToBytes(payload.dataBase64))
+		}
+		catch { /* keep waiting */ }
+		return false
+	}
+	return table.settle(requestId, null)
+}

package/files/{chunk_provider_registry.mjs → chunk/provider_registry.mjs}

@@ -10,7 +10,7 @@ const nodeHashProvidersByOwner = new Map()
  * @returns {void}
  */
 export function registerFederationChunkFetcher(ownerId, fetcher) {
-	federationFetchersByOwner.set(String(ownerId), fetcher)
+	federationFetchersByOwner.set(ownerId, fetcher)
 }
 
 /**
@@ -19,7 +19,7 @@ export function registerFederationChunkFetcher(ownerId, fetcher) {
  * @returns {void}
  */
 export function registerNodeHashProvider(ownerId, provider) {
-	nodeHashProvidersByOwner.set(String(ownerId), provider)
+	nodeHashProvidersByOwner.set(ownerId, provider)
 }
 
 /**
@@ -27,9 +27,8 @@ export function registerNodeHashProvider(ownerId, provider) {
  * @returns {void}
  */
 export function unregisterChunkProviders(ownerId) {
-	const key = String(ownerId)
-	federationFetchersByOwner.delete(key)
-	nodeHashProvidersByOwner.delete(key)
+	federationFetchersByOwner.delete(ownerId)
+	nodeHashProvidersByOwner.delete(ownerId)
 }
 
 /**