@steve02081504/fount-p2p 0.0.0

package/federation/dag_order_cache.mjs

@@ -0,0 +1,124 @@
+/**
+ * DAG 拓扑序磁盘缓存（events.order.json）：增量合并，避免每次全量 Kahn。
+ */
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import {
+	computeLocalTipsHash,
+	eventsToMetas,
+	sortedPrevEventIds,
+	topologicalCanonicalOrder,
+} from '../dag/index.mjs'
+import { computeDagTipIdsFromEvents } from '../governance/branch.mjs'
+
+/**
+ * 将新增事件按父指针插入已有拓扑序之后。
+ * @param {string[]} cachedOrder 已缓存序
+ * @param {object[]} events 全量事件
+ * @returns {string[]} 合并后的 id 序
+ */
+export function mergeTopologicalOrder(cachedOrder, events) {
+	const byId = new Map(events.map(event => [event.id, event]))
+	const merged = cachedOrder.filter(id => byId.has(id))
+	const orderSet = new Set(merged)
+	const newEvents = events.filter(event => !orderSet.has(event.id))
+	if (!newEvents.length) return merged
+
+	const newOrder = topologicalCanonicalOrder(eventsToMetas(newEvents))
+	for (const id of newOrder) {
+		if (orderSet.has(id)) continue
+		const event = byId.get(id)
+		let insertAt = merged.length
+		for (const parentId of sortedPrevEventIds(event?.prev_event_ids)) {
+			const parentIdx = merged.indexOf(parentId)
+			if (parentIdx >= 0) insertAt = Math.max(insertAt, parentIdx + 1)
+		}
+		merged.splice(insertAt, 0, id)
+		orderSet.add(id)
+	}
+	return merged
+}
+
+/**
+ * @param {object[]} events 全量事件
+ * @param {object | null} cache 磁盘缓存
+ * @param {{ forceFull?: boolean }} [opts] 选项
+ * @returns {string[]} 拓扑序 id 列表
+ */
+export function resolveEventTopologicalOrder(events, cache, opts = {}) {
+	if (!events.length) return []
+	if (opts.forceFull)
+		return topologicalCanonicalOrder(eventsToMetas(events))
+
+	const byId = new Map(events.map(event => [event.id, event]))
+	const tips = computeDagTipIdsFromEvents(events)
+	const tipsHash = computeLocalTipsHash(tips)
+	const eventCount = events.length
+
+	if (cache && Array.isArray(cache.order) && cache.order.length) {
+		if (cache.tipsHash === tipsHash && cache.eventCount === eventCount) {
+			const ok = cache.order.length === eventCount && cache.order.every(id => byId.has(id))
+			if (ok) return cache.order
+		}
+		if (cache.eventCount <= eventCount && cache.order.every(id => byId.has(id))) {
+			const merged = mergeTopologicalOrder(cache.order, events)
+			if (merged.length === eventCount) return merged
+		}
+	}
+
+	return topologicalCanonicalOrder(eventsToMetas(events))
+}
+
+/**
+ * @param {string[]} order 拓扑序
+ * @param {object[]} events 全量事件
+ * @returns {{ order: string[], tipsHash: string, eventCount: number }} 可写入 events.order.json
+ */
+export function buildOrderCachePayload(order, events) {
+	const tips = computeDagTipIdsFromEvents(events)
+	return {
+		order,
+		tipsHash: computeLocalTipsHash(tips),
+		eventCount: events.length,
+	}
+}
+
+/**
+ * @param {string} path `events.order.json` 路径
+ * @returns {Promise<object | null>} 缓存或 null
+ */
+export async function readOrderCache(path) {
+	try {
+		return JSON.parse(await readFile(path, 'utf8'))
+	}
+	catch {
+		return null
+	}
+}
+
+/**
+ * 写入拓扑序缓存。纯性能缓存：写失败（如群目录在并发清理/拆群时被删，Windows 上 open 报
+ * EPERM、或 ENOENT/EBUSY）不应让物化抛错或上浮告警，静默忽略即可，下次读盘自会重建。
+ * @param {string} path 路径
+ * @param {object} payload 缓存体
+ * @returns {Promise<void>}
+ */
+export async function writeOrderCache(path, payload) {
+	try {
+		await mkdir(dirname(path), { recursive: true })
+		await writeFile(path, JSON.stringify(payload), 'utf8')
+	}
+	catch { /* best-effort cache: dir removed mid-teardown / transient FS error */ }
+}
+
+/**
+ * @param {string} path 路径
+ * @returns {Promise<void>}
+ */
+export async function deleteOrderCache(path) {
+	try {
+		await unlink(path)
+	}
+	catch { /* absent */ }
+}

package/federation/dedupe_slot.mjs

@@ -0,0 +1,33 @@
+import { createLruMap } from '../utils/lru.mjs'
+
+/**
+ * TTL 去重槽：partition bridge、gossip 等共用。
+ */
+
+/**
+ * @param {{ maxSize?: number, ttlMs?: number }} [options] 容量与 TTL
+ * @returns {(key: string) => boolean} 首次占用返回 true
+ */
+export function createDedupeSlot(options = {}) {
+	const maxSize = Number(options.maxSize) || 2000
+	const ttlMs = Number(options.ttlMs) || 30_000
+	/** @type {Map<string, number>} */
+	const seen = createLruMap(maxSize)
+
+	/**
+	 * @param {string} key 去重键
+	 * @returns {boolean} 首次占用返回 true
+	 */
+	const take = key => {
+		const now = Date.now()
+		const seenAt = seen.get(key)
+		if (seenAt !== undefined) {
+			if (now - seenAt < ttlMs) return false
+			seen.delete(key)
+		}
+		seen.touch(key, now)
+		return true
+	}
+
+	return take
+}

package/federation/message_rate_limit.mjs

@@ -0,0 +1,23 @@
+/**
+ * 群级消息限速纯函数（无 I/O，供单测与 governance 复用）。
+ */
+
+/**
+ * @param {object} event DAG 事件
+ * @returns {string} 限速实体键
+ */
+export function messageRateEntityKey(event) {
+	const charId = String(event?.charId || '').trim()
+	if (charId) return `char:${charId}`
+	return String(event?.sender || '').trim().toLowerCase()
+}
+
+/**
+ * @param {object} groupSettings 群设置
+ * @returns {{ perMin: number, windowMs: number }} 每分钟条数与窗口毫秒
+ */
+export function resolveMessageRateLimits(groupSettings) {
+	const perMin = Math.max(1, Math.min(120, Number(groupSettings?.messageRateLimitPerMin) || 10))
+	const windowMs = Math.max(10_000, Number(groupSettings?.messageRateLimitWindowMs) || 60_000)
+	return { perMin, windowMs }
+}

package/federation/operator_key_chain.mjs

@@ -0,0 +1,200 @@
+/**
+ * Operator 密钥历史链：entityHash 锚定 recovery 公钥，活跃钥可轮换。
+ */
+import { Buffer } from 'node:buffer'
+
+import { canonicalStringify } from '../core/canonical_json.mjs'
+import { hashFromPubKeyHex } from '../core/entity_id.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+
+/**
+ *
+ */
+export const OPERATOR_KEY_REVOKE_DOMAIN = 'fount-operator-key-revoke'
+
+/**
+ * @typedef {{
+ *   generation: number,
+ *   activePubKeyHex: string,
+ *   attestedBy: 'recovery' | 'active' | 'revoked',
+ *   validFrom?: number,
+ *   revokedGenerations?: number[],
+ * }} OperatorKeyHistoryEntry
+ */
+
+/**
+ * @param {unknown} recoveryPubKeyHex 64 位十六进制 recovery 公钥
+ * @returns {string} 稳定 subjectHash（entityHash 后半）
+ */
+export function recoverySubjectHashFromPubKeyHex(recoveryPubKeyHex) {
+	return hashFromPubKeyHex(recoveryPubKeyHex)
+}
+
+/**
+ * @param {unknown} activePubKeyHex 64 位十六进制 活跃公钥
+ * @returns {string} 时间线 sender（pubKeyHash）
+ */
+export function activeSenderHashFromPubKeyHex(activePubKeyHex) {
+	return hashFromPubKeyHex(activePubKeyHex)
+}
+
+/**
+ * @param {string} recoveryPubKeyHex recovery 公钥
+ * @param {string} activePubKeyHex 初始活跃公钥
+ * @param {number} [validFrom] 生效时间
+ * @returns {OperatorKeyHistoryEntry[]} 创世链
+ */
+export function createGenesisKeyHistory(recoveryPubKeyHex, activePubKeyHex, validFrom = Date.now()) {
+	return [{
+		generation: 0,
+		activePubKeyHex: normalizeHex64(activePubKeyHex),
+		attestedBy: 'recovery',
+		validFrom,
+	}]
+}
+
+/**
+ * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {number} generation 代际
+ * @returns {string | null} 活跃公钥 hex
+ */
+export function resolveActiveKeyAtGeneration(keyHistory, generation) {
+	const entry = keyHistory.find(row => row.generation === generation)
+	return entry?.activePubKeyHex ?? null
+}
+
+/**
+ * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @returns {number} 最新代际，无则 -1
+ */
+export function resolveLatestActiveGeneration(keyHistory) {
+	if (!keyHistory?.length) return -1
+	return Math.max(...keyHistory.map(row => row.generation))
+}
+
+/**
+ * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {number} generation 代际
+ * @returns {boolean} 是否已吊销
+ */
+export function isActiveGenerationRevoked(keyHistory, generation) {
+	for (const entry of keyHistory)
+		if (entry.revokedGenerations?.includes(generation)) return true
+	return false
+}
+
+/**
+ * @param {OperatorKeyHistoryEntry[]} keyHistory 密钥历史
+ * @param {string} recoveryPubKeyHex recovery 公钥
+ * @param {string} senderPubKeyHash 事件 sender（64 hex pubKeyHash）
+ * @returns {boolean} sender 是否为未吊销的活跃钥
+ */
+export function isValidActiveSender(keyHistory, recoveryPubKeyHex, senderPubKeyHash) {
+	const sender = normalizeHex64(senderPubKeyHash)
+	if (!isHex64(sender)) return false
+	void recoveryPubKeyHex
+	for (const entry of keyHistory || []) {
+		if (isActiveGenerationRevoked(keyHistory, entry.generation)) continue
+		if (activeSenderHashFromPubKeyHex(entry.activePubKeyHex) === sender)
+			return true
+	}
+	return false
+}
+
+/**
+ * @param {string} recoveryPubKeyHex recovery 公钥
+ * @param {string} senderPubKeyHash 事件 sender
+ * @returns {boolean} 是否为 recovery 钥签名
+ */
+export function isRecoverySender(recoveryPubKeyHex, senderPubKeyHash) {
+	return recoverySubjectHashFromPubKeyHex(recoveryPubKeyHex) === normalizeHex64(senderPubKeyHash)
+}
+
+/**
+ * @param {object} state 物化状态
+ * @param {object} event operator_key_rotate 事件
+ * @returns {object} 更新后状态
+ */
+export function reduceOperatorKeyRotate(state, event) {
+	const generation = Number(event.content?.generation)
+	const activePubKeyHex = normalizeHex64(event.content?.activePubKeyHex || '')
+	if (!Number.isFinite(generation) || generation < 0 || !isHex64(activePubKeyHex))
+		return state
+	state.operatorKeyHistory = state.operatorKeyHistory || []
+	if (state.operatorKeyHistory.some(row => row.generation === generation))
+		return state
+	state.operatorKeyHistory.push({
+		generation,
+		activePubKeyHex,
+		attestedBy: generation === 0 ? 'recovery' : 'active',
+		validFrom: event.hlc?.wall ?? event.timestamp,
+	})
+	return state
+}
+
+/**
+ * @param {object} state 物化状态
+ * @param {object} event operator_key_revoke 事件
+ * @returns {object} 更新后状态
+ */
+export function reduceOperatorKeyRevoke(state, event) {
+	const newGeneration = Number(event.content?.newGeneration)
+	const activePubKeyHex = normalizeHex64(event.content?.activePubKeyHex || '')
+	const revokeGenerations = Array.isArray(event.content?.revokeGenerations)
+		? event.content.revokeGenerations.map(g => Number(g)).filter(Number.isFinite)
+		: []
+	if (!Number.isFinite(newGeneration) || newGeneration < 0 || !isHex64(activePubKeyHex))
+		return state
+	state.operatorKeyHistory = state.operatorKeyHistory || []
+	for (const gen of revokeGenerations) {
+		const entry = state.operatorKeyHistory.find(row => row.generation === gen)
+		if (entry) {
+			entry.revokedGenerations = entry.revokedGenerations || []
+			if (!entry.revokedGenerations.includes(gen))
+				entry.revokedGenerations.push(gen)
+		}
+	}
+	if (!state.operatorKeyHistory.some(row => row.generation === newGeneration))
+		state.operatorKeyHistory.push({
+			generation: newGeneration,
+			activePubKeyHex,
+			attestedBy: 'recovery',
+			validFrom: event.hlc?.wall ?? event.timestamp,
+		})
+
+	return state
+}
+/**
+ * @param {object[]} events 时间线事件（拓扑序）
+ * @returns {{ recoveryPubKeyHex: string | null, operatorKeyHistory: OperatorKeyHistoryEntry[] }} 折叠密钥链
+ */
+export function foldOperatorKeyHistoryFromEvents(events) {
+	/** @type {OperatorKeyHistoryEntry[]} */
+	let operatorKeyHistory = []
+	for (const event of events || []) {
+		if (event.type === 'operator_key_rotate') {
+			const state = reduceOperatorKeyRotate({ operatorKeyHistory }, event)
+			operatorKeyHistory = state.operatorKeyHistory
+		}
+		if (event.type === 'operator_key_revoke') {
+			const state = reduceOperatorKeyRevoke({ operatorKeyHistory }, event)
+			operatorKeyHistory = state.operatorKeyHistory
+		}
+	}
+	return { recoveryPubKeyHex: null, operatorKeyHistory }
+}
+
+/**
+ * @param {object} revokeBody 吊销正文
+ * @returns {Buffer} 固定域签名消息
+ */
+export function operatorKeyRevokeSignBytes(revokeBody) {
+	const body = {
+		revokeGenerations: (revokeBody.revokeGenerations || []).map(g => Number(g)),
+		newGeneration: Number(revokeBody.newGeneration),
+		activePubKeyHex: normalizeHex64(revokeBody.activePubKeyHex || ''),
+		entityHash: String(revokeBody.entityHash || '').trim().toLowerCase(),
+	}
+	return Buffer.from(`${OPERATOR_KEY_REVOKE_DOMAIN}\0${canonicalStringify(body)}`, 'utf8')
+}
+

package/federation/topo_order_memo.mjs

@@ -0,0 +1,44 @@
+import { eventsToMetas, topologicalCanonicalOrder } from '../dag/index.mjs'
+
+/** @type {Map<string, { fp: string, order: string[] }>} */
+const memoByKey = new Map()
+
+/**
+ * 进程内拓扑序 memo（key 由调用方提供，如 username:groupId）。
+ * @param {string} memoKey 缓存键
+ * @param {string} fingerprint 文件 stat + 事件数指纹
+ * @param {object[]} events 全量事件
+ * @param {{ force?: boolean }} [opts] 强制重算
+ * @returns {string[]} 拓扑序 event id
+ */
+export function resolveTopologicalOrderMemo(memoKey, fingerprint, events, opts = {}) {
+	return resolveTopologicalOrderMemoCached(memoKey, fingerprint, () =>
+		topologicalCanonicalOrder(eventsToMetas(events)), opts)
+}
+
+/**
+ * 进程内拓扑序 memo；`resolveOrder` 可接入磁盘缓存等实现。
+ * @param {string} memoKey 缓存键
+ * @param {string} fingerprint 文件 stat + 事件数指纹
+ * @param {() => string[]} resolveOrder 实际求序（含磁盘层）
+ * @param {{ force?: boolean }} [opts] 强制重算
+ * @returns {string[]} 拓扑序 event id
+ */
+export function resolveTopologicalOrderMemoCached(memoKey, fingerprint, resolveOrder, opts = {}) {
+	if (!opts.force) {
+		const cached = memoByKey.get(memoKey)
+		if (cached?.fp === fingerprint && cached.order.length)
+			return cached.order
+	}
+	const order = resolveOrder()
+	memoByKey.set(memoKey, { fp: fingerprint, order })
+	return order
+}
+
+/**
+ * @param {string} memoKey 缓存键
+ * @returns {void}
+ */
+export function invalidateTopologicalOrderMemo(memoKey) {
+	memoByKey.delete(memoKey)
+}

package/federation/volatile_streams.mjs

@@ -0,0 +1,52 @@
+/**
+ * VOLATILE 流：`stream_chunk` 按 chunkSeq 缓冲 slices JSON；终稿由 DAG message_edit 结束（§6.4）。
+ *
+ * @returns {object} 含 addChunk/end/listChunks/clear 的 API 对象
+ */
+export function createVolatileStreamBuffer() {
+	/** @type {Map<string, { chunks: Map<number, string>, ended: boolean }>} */
+	const streams = new Map()
+
+	return {
+		/**
+		 * @param {string} pendingStreamId 流 ID
+		 * @param {number} chunkSeq 分片序号
+		 * @param {string} payload JSON 序列化的 slices
+		 * @returns {void}
+		 */
+		addChunk(pendingStreamId, chunkSeq, payload) {
+			let stream = streams.get(pendingStreamId)
+			if (!stream) {
+				stream = { chunks: new Map(), ended: false }
+				streams.set(pendingStreamId, stream)
+			}
+			if (!stream.ended) stream.chunks.set(chunkSeq, payload)
+		},
+		/**
+		 * @param {string} pendingStreamId 流 ID
+		 * @returns {void}
+		 */
+		end(pendingStreamId) {
+			const stream = streams.get(pendingStreamId)
+			if (stream) stream.ended = true
+		},
+		/**
+		 * @param {string} pendingStreamId 流 ID
+		 * @returns {{ chunkSeq: number, payload: string }[]} 升序分片列表
+		 */
+		listChunks(pendingStreamId) {
+			const stream = streams.get(pendingStreamId)
+			if (!stream) return []
+			return [...stream.chunks.entries()]
+				.sort((a, b) => a[0] - b[0])
+				.map(([chunkSeq, payload]) => ({ chunkSeq, payload }))
+		},
+		/**
+		 * @param {string} pendingStreamId 流 ID
+		 * @returns {void}
+		 */
+		clear(pendingStreamId) {
+			streams.delete(pendingStreamId)
+		},
+	}
+}

package/federation/want_ids.mjs

@@ -0,0 +1,158 @@
+/**
+ * wantIds 限速与退避（§9）：每邻居 QPS/突发、出站批预算、指数退避冷却。
+ */
+
+const DEFAULT_IN_WINDOW_MS = 60_000
+const DEFAULT_IN_MAX_BATCH = 32
+const DEFAULT_OUT_WINDOW_MS = 60_000
+const DEFAULT_OUT_MAX_BATCH = 16
+const DEFAULT_BACKOFF_BASE_MS = 2_000
+const DEFAULT_BACKOFF_MAX_MS = 120_000
+
+/** @type {Map<string, { count: number, resetAt: number }>} */
+const inboundByKey = new Map()
+/** @type {Map<string, { count: number, resetAt: number }>} */
+const outboundByKey = new Map()
+/** @type {Map<string, { until: number, strikes: number }>} */
+const backoffByKey = new Map()
+
+/**
+ * 清理过期速率窗口条目。
+ * @param {Map<string, { count: number, resetAt: number }>} map 速率表
+ * @param {number} maxSize 触发清理的上限
+ * @param {number} now 当前时间戳
+ * @returns {void} 无返回值
+ */
+function pruneRateMap(map, maxSize, now) {
+	if (map.size <= maxSize) return
+	for (const [k, v] of map)
+		if (now > v.resetAt + 120_000) map.delete(k)
+}
+
+/**
+ * 解析 wantIds 限速参数。
+ * @param {object} [limits] 可选覆盖
+ * @param {number} [limits.inWindowMs] 入站窗口毫秒
+ * @param {number} [limits.inMaxBatch] 入站每窗口批次数
+ * @param {number} [limits.outWindowMs] 出站窗口毫秒
+ * @param {number} [limits.outMaxBatch] 出站每窗口批次数
+ * @returns {{ inWindowMs: number, inMaxBatch: number, outWindowMs: number, outMaxBatch: number }} 生效限额
+ */
+export function resolveWantIdsLimits(limits = {}) {
+	return {
+		inWindowMs: Math.max(1000, Number(limits.inWindowMs) || DEFAULT_IN_WINDOW_MS),
+		inMaxBatch: Math.max(1, Math.min(256, Number(limits.inMaxBatch) || DEFAULT_IN_MAX_BATCH)),
+		outWindowMs: Math.max(1000, Number(limits.outWindowMs) || DEFAULT_OUT_WINDOW_MS),
+		outMaxBatch: Math.max(1, Math.min(256, Number(limits.outMaxBatch) || DEFAULT_OUT_MAX_BATCH)),
+	}
+}
+
+/**
+ * @param {string} groupId 群 ID
+ * @param {string} peerId 对端节点 id
+ * @returns {string} 复合键
+ */
+export function wantIdsPeerKey(groupId, peerId) {
+	return `${groupId}\0${peerId}`
+}
+
+/**
+ * 出站 want 限速键。
+ * @param {string} groupId 群 ID
+ * @returns {string} 复合键
+ */
+export function wantIdsGroupKey(groupId) {
+	return groupId
+}
+
+/**
+ * 是否处于 wantIds 退避冷却。
+ * @param {string} key 限速或退避键
+ * @returns {boolean} 冷却中则为 true
+ */
+export function isWantIdsInBackoff(key) {
+	const b = backoffByKey.get(key)
+	if (!b) return false
+	if (Date.now() < b.until) return true
+	backoffByKey.delete(key)
+	return false
+}
+
+/**
+ * 记录一次 wantIds 超限并延长退避。
+ * @param {string} key 退避键
+ * @returns {void} 无返回值
+ */
+export function recordWantIdsBackoff(key) {
+	const now = Date.now()
+	const prev = backoffByKey.get(key)
+	const strikes = (prev?.strikes ?? 0) + 1
+	const delay = Math.min(
+		DEFAULT_BACKOFF_MAX_MS,
+		DEFAULT_BACKOFF_BASE_MS * 2 ** Math.min(strikes - 1, 6),
+	)
+	backoffByKey.set(key, { until: now + delay, strikes })
+	if (backoffByKey.size > 12_000)
+		for (const [k, v] of backoffByKey)
+			if (now > v.until) backoffByKey.delete(k)
+}
+
+/**
+ * 消耗入站 want 配额。
+ * @param {string} username 用户名
+ * @param {string} groupId 群 ID
+ * @param {string} requesterId 请求方节点 id
+ * @param {object} [limits] 可选限额
+ * @returns {boolean} 允许处理则为 true
+ */
+export function takeIncomingWantIdsSlot(groupId, requesterId, limits) {
+	const { inWindowMs, inMaxBatch } = resolveWantIdsLimits(limits)
+	const peerKey = wantIdsPeerKey(groupId, requesterId)
+	if (isWantIdsInBackoff(peerKey)) return false
+	const now = Date.now()
+	let e = inboundByKey.get(peerKey)
+	if (!e || now > e.resetAt) e = { count: 0, resetAt: now + inWindowMs }
+	if (e.count >= inMaxBatch) {
+		recordWantIdsBackoff(peerKey)
+		return false
+	}
+	e.count++
+	inboundByKey.set(peerKey, e)
+	pruneRateMap(inboundByKey, 8000, now)
+	return true
+}
+
+/**
+ * 消耗出站 want 配额。
+ * @param {string} username 用户名
+ * @param {string} groupId 群 ID
+ * @param {object} [limits] 可选限额
+ * @returns {boolean} 允许发起则为 true
+ */
+export function takeOutgoingWantIdsSlot(groupId, limits) {
+	const { outWindowMs, outMaxBatch } = resolveWantIdsLimits(limits)
+	const key = wantIdsGroupKey(groupId)
+	if (isWantIdsInBackoff(key)) return false
+	const now = Date.now()
+	let e = outboundByKey.get(key)
+	if (!e || now > e.resetAt) e = { count: 0, resetAt: now + outWindowMs }
+	if (e.count >= outMaxBatch) {
+		recordWantIdsBackoff(key)
+		return false
+	}
+	e.count++
+	outboundByKey.set(key, e)
+	pruneRateMap(outboundByKey, 4000, now)
+	return true
+}
+
+/**
+ * 按预算截断 wantIds 列表。
+ * @param {string[]} wantIds 缺失事件 id
+ * @param {number} budget 单批上限
+ * @returns {string[]} 截断后的 id 列表
+ */
+export function batchWantIds(wantIds, budget) {
+	const cap = Math.max(1, Math.min(256, Number(budget) || DEFAULT_OUT_MAX_BATCH))
+	return wantIds.slice(0, cap)
+}