@steve02081504/fount-p2p 0.0.22 → 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/entity_id.mjs

@@ -1,7 +1,6 @@
-import { Buffer } from 'node:buffer'
-
 import { pubKeyHash } from '../crypto/crypto.mjs'
 
+import { hexToBytes } from './bytes_codec.mjs'
 import {
 	encodeEntityHash,
 	ENTITY_HASH_RE,
@@ -26,9 +25,10 @@ export {
  */
 export function hashFromPubKeyHex(pubKeyHex) {
 	const hex = normalizeHex64(pubKeyHex)
-	if (!isHex64(hex) || Buffer.from(hex, 'hex').length !== 32)
-		throw new Error('invalid pubKeyHex')
-	return pubKeyHash(Buffer.from(hex, 'hex'))
+	if (!isHex64(hex)) throw new Error('invalid pubKeyHex')
+	const bytes = hexToBytes(hex)
+	if (bytes.length !== 32) throw new Error('invalid pubKeyHex')
+	return pubKeyHash(bytes)
 }
 
 /**

package/core/logical_entity.mjs

@@ -1,6 +1,6 @@
 import { sha256TextHex } from '../crypto/crypto.mjs'
 
-import { encodeEntityHash, parseEntityHash } from './entity_id.mjs'
+import { encodeEntityHash, parseEntityHash } from './entity_id_parse.mjs'
 
 /** @type {string} 逻辑实体 sentinel nodeHash（非物理节点绑定） */
 export const LOGICAL_ENTITY_SENTINEL_NODE_HASH = '0'.repeat(64)

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/core/random_id.mjs

@@ -1,9 +1,11 @@
-import { randomUUID } from 'node:crypto'
+/**
+ * 跨端随机 ID（Web Crypto / Node globalThis.crypto）。
+ */
 
 /**
  * @param {string} prefix ID 前缀（如 channel_）
  * @returns {string} 带前缀的随机 ID
  */
 export function prefixedRandomId(prefix) {
-	return `${prefix}${randomUUID().replace(/-/g, '')}`
+	return `${prefix}${globalThis.crypto.randomUUID().replace(/-/g, '')}`
 }

package/crypto/crypto.mjs

@@ -1,105 +1,65 @@
-import { Buffer } from 'node:buffer'
-import {
-	createHash,
-	createPrivateKey,
-	createPublicKey,
-	randomBytes,
-	sign as nodeSign,
-	verify as nodeVerify,
-} from 'node:crypto'
-
-/** 固定 DER 头（非秘密），让 Node 把 32 字节种子当成私钥 */
-const PKCS8_RAW_SEED_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex')
-/** 固定 DER 头（非秘密），让 Node 把 32 字节当成公钥 */
-const SPKI_RAW_PUB_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
-
 /**
- * @param {Uint8Array|Buffer} seed32 32 字节私钥种子
- * @returns {import('node:crypto').KeyObject} Node 私钥对象
+ * 跨端 Ed25519 / SHA-256（Node 与浏览器共用；不依赖 node:crypto）。
  */
-function privateKeyFromSeed(seed32) {
-	return createPrivateKey({
-		key: Buffer.concat([PKCS8_RAW_SEED_PREFIX, Buffer.from(seed32).subarray(0, 32)]),
-		format: 'der',
-		type: 'pkcs8',
-	})
-}
+import { ed25519 } from '@noble/curves/ed25519.js'
+import { sha256 } from '@noble/hashes/sha2.js'
 
-/**
- * @param {Uint8Array|Buffer} rawPublicKey 32 字节公钥
- * @returns {import('node:crypto').KeyObject} Node 公钥对象
- */
-function publicKeyFromRaw(rawPublicKey) {
-	return createPublicKey({
-		key: Buffer.concat([SPKI_RAW_PUB_PREFIX, Buffer.from(rawPublicKey).subarray(0, 32)]),
-		format: 'der',
-		type: 'spki',
-	})
-}
+import { bytesToHex, toBytes } from '../core/bytes_codec.mjs'
 
 /**
- * @param {Uint8Array|Buffer} seed32 32 字节私钥种子
- * @returns {Uint8Array} 32 字节公钥
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer|string} data 字节或 UTF-8 文本
+ * @returns {Uint8Array} 规范化字节
  */
-function rawPublicKeyFromSeed(seed32) {
-	const der = createPublicKey(privateKeyFromSeed(seed32)).export({ type: 'spki', format: 'der' })
-	return new Uint8Array(der.subarray(-32))
+function inputBytes(data) {
+	if (typeof data === 'string') return new TextEncoder().encode(data)
+	return toBytes(data)
 }
 
 /**
- * 由种子字节派生密钥对
- *
- * @param {Uint8Array|Buffer} seed 任意长度；非 32 字节时 sha256 派生
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer} seed 任意长度；非 32 字节时 sha256 派生
  * @returns {{ publicKey: Uint8Array, secretKey: Uint8Array }} 32 字节私钥与对应公钥
  */
 export function keyPairFromSeed(seed) {
-	const u = seed instanceof Uint8Array ? seed : new Uint8Array(seed)
-	const sk = u.length === 32 ? u : new Uint8Array(createHash('sha256').update(u).digest())
-	return { publicKey: rawPublicKeyFromSeed(sk), secretKey: new Uint8Array(sk) }
+	const u = toBytes(seed)
+	const sk = u.length === 32 ? u : sha256(u)
+	return { publicKey: ed25519.getPublicKey(sk), secretKey: new Uint8Array(sk) }
 }
 
 /**
- * 随机生成密钥对
- *
  * @returns {Promise<{ publicKey: Uint8Array, secretKey: Uint8Array }>} 随机密钥对
  */
 export async function randomKeyPair() {
-	const sk = randomBytes(32)
+	const sk = new Uint8Array(32)
+	globalThis.crypto.getRandomValues(sk)
 	return keyPairFromSeed(sk)
 }
 
 /**
- * 由 32 字节私钥种子导出对应公钥
  * @param {Uint8Array} secretKey 私钥种子
  * @returns {Uint8Array} 公钥
  */
 export function publicKeyFromSeed(secretKey) {
-	return rawPublicKeyFromSeed(secretKey)
+	return ed25519.getPublicKey(toBytes(secretKey).subarray(0, 32))
 }
 
 /**
- * 签名
- *
- * @param {Uint8Array} message 待签名消息字节
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer|string} message 待签名消息
  * @param {Uint8Array} secretKey 私钥（取前 32 字节为种子）
  * @returns {Promise<Uint8Array>} 64 字节签名
  */
 export async function sign(message, secretKey) {
-	const sig = nodeSign(null, Buffer.from(message), privateKeyFromSeed(secretKey))
-	return new Uint8Array(sig)
+	return ed25519.sign(inputBytes(message), toBytes(secretKey).subarray(0, 32))
 }
 
 /**
- * 校验签名
- *
- * @param {Uint8Array} signature 64 字节签名
- * @param {Uint8Array} message 原始消息字节
- * @param {Uint8Array} publicKey 公钥
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer} signature 64 字节签名
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer|string} message 原始消息
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer} publicKey 公钥
  * @returns {Promise<boolean>} 合法为 true；异常或失败为 false
  */
 export async function verify(signature, message, publicKey) {
 	try {
-		return nodeVerify(null, Buffer.from(message), publicKeyFromRaw(publicKey), Buffer.from(signature))
+		return ed25519.verify(toBytes(signature), inputBytes(message), toBytes(publicKey))
 	}
 	catch {
 		return false
@@ -107,52 +67,25 @@ export async function verify(signature, message, publicKey) {
 }
 
 /**
- * 公钥的 sha256 十六进制指纹（小写、无 0x 前缀）
- *
- * @param {Uint8Array} publicKey 公钥字节
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer} publicKey 公钥字节
  * @returns {string} 64 字符 hex
  */
 export function pubKeyHash(publicKey) {
-	return bufferToHexSimple(hashPubKeyBytes(publicKey))
-}
-
-/**
- * 公钥 sha256 摘要
- *
- * @param {Uint8Array} publicKey 公钥字节
- * @returns {Buffer} 32 字节 digest
- */
-function hashPubKeyBytes(publicKey) {
-	return createHash('sha256').update(publicKey).digest()
+	return bytesToHex(sha256(toBytes(publicKey)))
 }
 
 /**
- * 任意输入的 SHA-256 十六进制（小写、无 0x 前缀）。
- *
- * @param {Uint8Array|Buffer|string} data 字节或 UTF-8 文本
+ * @param {Uint8Array|ArrayBufferView|ArrayBuffer|string} data 字节或 UTF-8 文本
  * @returns {string} 64 字符 hex
  */
 export function sha256Hex(data) {
-	const input = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data)
-	return createHash('sha256').update(input).digest('hex')
+	return bytesToHex(sha256(inputBytes(data)))
 }
 
 /**
- * UTF-8 文本 SHA-256 十六进制（小写、无 0x 前缀）。
- *
  * @param {string} text 文本
  * @returns {string} 64 字符 hex
  */
 export function sha256TextHex(text) {
 	return sha256Hex(String(text ?? ''))
 }
-
-/**
- * Buffer / Uint8Array → 小写 hex 字符串
- *
- * @param {Uint8Array|Buffer} buffer 二进制缓冲
- * @returns {string} 小写十六进制文本
- */
-function bufferToHexSimple(buffer) {
-	return Buffer.from(buffer).toString('hex')
-}

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 {