@steve02081504/fount-p2p 0.0.0

package/node/instance.mjs

@@ -0,0 +1,115 @@
+import path from 'node:path'
+
+import { createFsEntityStore } from './entity_store.mjs'
+import { defaultSignalingRuntimeConfig, resolveSignalingRuntimeConfig } from './signaling_config.mjs'
+
+/** @typedef {{ warn?: (...args: unknown[]) => void, error?: (...args: unknown[]) => void }} NodeLogger */
+
+/** @typedef {import('./signaling_config.mjs').SignalingRuntimeConfig} SignalingRuntimeConfig */
+
+/**
+ * @typedef {{
+ *   nodeDir: string
+ *   entityStore: import('./entity_store.mjs').EntityStore
+ *   logger: NodeLogger
+ *   signaling: SignalingRuntimeConfig
+ * }} NodeRuntime
+ */
+
+/** @type {NodeRuntime | null} */
+let runtime = null
+
+/** @type {Set<(event: string, payload?: unknown) => void>} */
+const changeListeners = new Set()
+
+/** @type {NodeLogger} */
+const noopLogger = {
+	/**
+	 *
+	 */
+	warn() { },
+	/**
+	 *
+	 */
+	error() { },
+}
+
+/**
+ * @param {{ nodeDir: string, entityStore?: import('./entity_store.mjs').EntityStore, logger?: NodeLogger, signaling?: SignalingRuntimeConfig }} options 节点目录与可选注入
+ * @returns {NodeRuntime} 单节点运行时句柄
+ */
+export function initNode(options) {
+	const nodeDir = path.resolve(String(options.nodeDir || '').trim())
+	if (!nodeDir) throw new Error('p2p: initNode requires nodeDir')
+	const entityStore = options.entityStore ?? createFsEntityStore(path.join(nodeDir, 'entities'))
+	runtime = {
+		nodeDir,
+		entityStore,
+		logger: options.logger ?? console,
+		signaling: options.signaling ?? resolveSignalingRuntimeConfig(),
+	}
+	return runtime
+}
+
+/**
+ * @returns {NodeRuntime} 已初始化的节点运行时
+ */
+export function getNode() {
+	if (!runtime) throw new Error('p2p: node not initialized — call initNode() first')
+	return runtime
+}
+
+/**
+ * @returns {boolean} 是否已调用 initNode
+ */
+export function isNodeInitialized() {
+	return runtime != null
+}
+
+/**
+ * @returns {SignalingRuntimeConfig} 信令传输策略（未 init 时返回生产默认，不读测试 env）
+ */
+export function getSignalingRuntimeConfig() {
+	return runtime?.signaling ?? defaultSignalingRuntimeConfig()
+}
+
+/**
+ * @returns {string} 节点数据目录绝对路径
+ */
+export function getNodeDir() {
+	return getNode().nodeDir
+}
+
+/**
+ * @returns {import('./entity_store.mjs').EntityStore} 注入的 EntityStore
+ */
+export function getEntityStore() {
+	return getNode().entityStore
+}
+
+/**
+ * @returns {NodeLogger} 节点日志器（未 init 时为 no-op）
+ */
+export function getNodeLogger() {
+	return runtime?.logger ?? noopLogger
+}
+
+/**
+ * @param {string} event 事件名
+ * @param {unknown} [payload] 载荷
+ * @returns {void}
+ */
+export function emitNodeChange(event, payload) {
+	for (const listener of changeListeners)
+		try { listener(event, payload) }
+		catch { /* ignore */ }
+}
+
+/**
+ * @param {(event: string, payload?: unknown) => void} listener 回调
+ * @returns {() => void} 取消订阅
+ */
+export function onNodeChange(listener) {
+	changeListeners.add(listener)
+	return () => changeListeners.delete(listener)
+}

package/node/network.mjs

@@ -0,0 +1,306 @@
+import { isEntityHash128 } from '../core/entity_id.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { invalidateTrustGraphCache } from '../trust_graph/cache.mjs'
+
+import { loadDenylist } from './denylist.mjs'
+import { getNodeDir, isNodeInitialized } from './instance.mjs'
+import { readNodeJsonSync, writeNodeJsonSync } from './storage.mjs'
+
+
+/**
+ * 联邦术语（Wave 6）：
+ * - **block**：Social 对外联邦公开拉黑（personal_block / timeline block 事件）
+ * - **hide**：纯本地隐藏（personal_hide，不联邦）
+ * - **deny**：节点连接拒绝（denylist.json，scope node/subject/entity）
+ * - **ban**：群成员治理（member_ban DAG + bannedMembers 物化态）
+ *
+ * @typedef {{
+ *   trustedPeers: string[]
+ *   explorePeers: string[]
+ *   blockedPeers: string[]
+ *   deniedNodes: string[]
+ *   deniedSubjects: string[]
+ *   deniedEntities: string[]
+ *   lastRosterAt: number
+ *   hintSources?: Map<string, string>
+ * }} PeerPoolView
+ */
+
+const DATA_NAME = 'network'
+const MAX_EXPLORE = 500
+const MAX_HINTS = 256
+const MAX_HINTS_PER_SOURCE = 12
+const DEFAULT_EXPLORE_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+/** @type {ReturnType<typeof normalizeNetwork> | null} network.json 内存缓存（唯一写路径 saveNetwork 负责刷新） */
+let networkCache = null
+/** @type {string | null} 缓存所属 nodeDir（切换节点/未初始化时失效） */
+let networkCacheNodeDir = null
+
+/**
+ * @typedef {{ nodeHash: string, source: string, kind: string, weight?: number, expiresAt: number, groupId?: string }} NetworkHint
+ */
+
+/**
+ * @param {unknown} raw 磁盘 JSON
+ * @returns {{ trustedPeers: string[], explorePeers: string[], hints: NetworkHint[], lastRosterAt: number }} 规范化网络表
+ */
+export function normalizeNetwork(raw) {
+	const file = raw ?? {}
+	/**
+	 * @param {string} key 字段名
+	 * @returns {string[]} 去重 nodeHash 列表
+	 */
+	const pickIds = key => [...new Set(
+		(Array.isArray(file[key]) ? file[key] : [])
+			.map(id => normalizeHex64(id) || String(id).trim())
+			.filter(id => isHex64(id)),
+	)]
+	const hints = (Array.isArray(file.hints) ? file.hints : [])
+		.map(hint => ({
+			nodeHash: normalizeHex64(hint?.nodeHash) || '',
+			source: String(hint?.source || '').trim(),
+			kind: String(hint?.kind || '').trim(),
+			weight: Number.isFinite(Number(hint?.weight)) ? Number(hint.weight) : 0.1,
+			expiresAt: Number(hint?.expiresAt) || 0,
+			...hint?.groupId ? { groupId: String(hint.groupId).trim() } : {},
+		}))
+		.filter(hint => isHex64(hint.nodeHash))
+	return {
+		trustedPeers: pickIds('trustedPeers'),
+		explorePeers: pickIds('explorePeers'),
+		hints,
+		lastRosterAt: Number.isFinite(file.lastRosterAt) ? Number(file.lastRosterAt) : 0,
+	}
+}
+
+/**
+ * 节点级 P2P 网络（内存缓存；热路径 loadPeerPoolView 每首见事件都会调用，避免每次同步读盘）。
+ * @returns {{ trustedPeers: string[], explorePeers: string[], hints: NetworkHint[], lastRosterAt: number }} 节点级 P2P 网络
+ */
+export function loadNetwork() {
+	const nodeDir = isNodeInitialized() ? getNodeDir() : ''
+	if (networkCache && networkCacheNodeDir === nodeDir) return networkCache
+	networkCacheNodeDir = nodeDir
+	networkCache = normalizeNetwork(readNodeJsonSync(DATA_NAME))
+	return networkCache
+}
+
+/**
+ * 限制同一 source 的 hint 数量，防止 PEX/单源灌满 explore。
+ * @param {NetworkHint[]} hints hint 列表
+ * @param {number} [maxPerSource=MAX_HINTS_PER_SOURCE] 每源上限
+ * @returns {NetworkHint[]} 裁剪后列表（保留较新条目）
+ */
+export function capHintsBySource(hints, maxPerSource = MAX_HINTS_PER_SOURCE) {
+	/** @type {Map<string, number>} */
+	const counts = new Map()
+	const out = []
+	for (const hint of [...hints].reverse()) {
+		const src = String(hint.source || 'unknown')
+		const n = counts.get(src) ?? 0
+		if (n >= maxPerSource) continue
+		counts.set(src, n + 1)
+		out.unshift(hint)
+	}
+	return out
+}
+
+/**
+ * @param {ReturnType<typeof normalizeNetwork>} data 网络表
+ * @returns {void}
+ */
+export function saveNetwork(data) {
+	const clean = normalizeNetwork(data)
+	const now = Date.now()
+	clean.hints = capHintsBySource(clean.hints.filter(h => !h.expiresAt || h.expiresAt > now)).slice(-MAX_HINTS)
+	clean.explorePeers = clean.explorePeers.slice(-MAX_EXPLORE)
+	writeNodeJsonSync(DATA_NAME, clean)
+	networkCache = clean
+	networkCacheNodeDir = isNodeInitialized() ? getNodeDir() : ''
+	invalidateTrustGraphCache()
+}
+
+/**
+ * @param {string} nodeHash 64 位十六进制
+ * @param {'trusted' | 'explore'} tier 池档位
+ * @returns {void}
+ */
+export function addNetworkPeer(nodeHash, tier = 'explore') {
+	const id = normalizeHex64(nodeHash)
+	if (!isHex64(id)) return
+	const net = loadNetwork()
+	const list = tier === 'trusted' ? net.trustedPeers : net.explorePeers
+	if (!list.includes(id)) list.push(id)
+	saveNetwork(net)
+}
+
+/**
+ * @param {{ nodeHash: string, source: string, kind: string, weight?: number, expiresAt?: number, ttlMs?: number, groupId?: string }} hint 扩边 hint
+ * @returns {void}
+ */
+export function applyNetworkHint(hint) {
+	const nodeHash = normalizeHex64(hint?.nodeHash)
+	if (!isHex64(nodeHash)) return
+	const net = loadNetwork()
+	const now = Date.now()
+	const ttlMs = Number.isFinite(hint.ttlMs) ? hint.ttlMs : DEFAULT_EXPLORE_TTL_MS
+	const expiresAt = Number.isFinite(hint.expiresAt) ? hint.expiresAt : now + ttlMs
+	const source = String(hint.source || 'unknown')
+	const priorSources = new Set(net.hints.filter(h => h.nodeHash === nodeHash).map(h => String(h.source || 'unknown')))
+	priorSources.add(source)
+	const multiSourceBoost = priorSources.size >= 2 ? 1.2 : 1
+	const baseWeight = Number.isFinite(hint.weight) ? hint.weight : 0.1
+	if (!net.explorePeers.includes(nodeHash))
+		net.explorePeers.push(nodeHash)
+	net.hints = net.hints.filter(h => h.nodeHash !== nodeHash || h.kind !== hint.kind)
+	net.hints.push({
+		nodeHash,
+		source,
+		kind: String(hint.kind || 'hint'),
+		weight: baseWeight * multiSourceBoost,
+		expiresAt,
+		...hint.groupId ? { groupId: String(hint.groupId).trim() } : {},
+	})
+	saveNetwork(net)
+}
+
+/**
+ * @param {{ remoteNodeHash?: string }[]} roster Trystero roster
+ * @param {string} [groupId] 来源群
+ * @param {string} [source='roster'] hint 来源标签
+ * @returns {void}
+ */
+export function recordExplorePeersFromRoster(roster, groupId = '', source = 'roster') {
+	if (!roster?.length) return
+	const net = loadNetwork()
+	const now = Date.now()
+	for (const peer of roster) {
+		const nodeHash = normalizeHex64(peer?.remoteNodeHash)
+		if (!isHex64(nodeHash)) continue
+		if (!net.explorePeers.includes(nodeHash))
+			net.explorePeers.push(nodeHash)
+		net.hints.push({
+			nodeHash,
+			source: String(source || 'roster'),
+			kind: 'roster',
+			weight: 0.1,
+			expiresAt: now + 24 * 60 * 60 * 1000,
+			...groupId ? { groupId: String(groupId).trim() } : {},
+		})
+	}
+	net.hints = capHintsBySource(net.hints).slice(-MAX_HINTS)
+	net.lastRosterAt = now
+	saveNetwork(net)
+}
+
+/**
+ * 疑似分区/eclipse 后：用 trusted 锚点加宽 explore，便于恢复联邦可达。
+ * @returns {void}
+ */
+export function widenExploreFromTrustedAnchors() {
+	if (!isNodeInitialized()) return
+	const net = loadNetwork()
+	const now = Date.now()
+	for (const raw of net.trustedPeers.slice(0, 12)) {
+		const nodeHash = normalizeHex64(raw)
+		if (!isHex64(nodeHash)) continue
+		if (!net.explorePeers.includes(nodeHash))
+			net.explorePeers.push(nodeHash)
+		net.hints.push({
+			nodeHash,
+			source: 'recovery:trusted',
+			kind: 'partition_recovery',
+			weight: 0.35,
+			expiresAt: now + 6 * 60 * 60 * 1000,
+		})
+	}
+	net.hints = capHintsBySource(net.hints).slice(-MAX_HINTS)
+	net.explorePeers = net.explorePeers.slice(-MAX_EXPLORE)
+	saveNetwork(net)
+}
+
+/**
+ * 增量合并 trusted/explore 池（不覆盖已有全局池）。
+ * @param {{ trustedPeers?: string[], explorePeers?: string[] }} patch 增量
+ * @returns {void}
+ */
+export function mergeNetworkPeerPools(patch = {}) {
+	const net = loadNetwork()
+	for (const raw of patch.trustedPeers || []) {
+		const id = normalizeHex64(raw)
+		if (isHex64(id) && !net.trustedPeers.includes(id)) net.trustedPeers.push(id)
+	}
+	for (const raw of patch.explorePeers || []) {
+		const id = normalizeHex64(raw)
+		if (isHex64(id) && !net.explorePeers.includes(id)) net.explorePeers.push(id)
+	}
+	net.lastRosterAt = Date.now()
+	saveNetwork(net)
+}
+
+/**
+ * @param {string[]} nodeHashes trusted 候选
+ * @returns {void}
+ */
+export function mergeTrustedPeers(nodeHashes) {
+	mergeNetworkPeerPools({ trustedPeers: nodeHashes })
+}
+
+/**
+ * @param {string} groupId 群 scope
+ * @param {'node' | 'subject' | 'entity'} scope denylist 作用域
+ * @returns {string[]} 规范化 value 列表
+ */
+function denyValuesForScope(groupId, scope) {
+	const gid = String(groupId || '').trim()
+	return [...new Set(
+		loadDenylist().blocked
+			.filter(entry => entry.scope === scope)
+			.filter(entry => scope === 'entity' || !entry.groupId || !gid || entry.groupId === gid)
+			.map(entry => entry.value),
+	)]
+}
+
+/**
+ * 节点级 network + 群 scope denylist 视图（供 peer_pool 选取）。
+ * deniedNodes 用于连接池过滤；deniedSubjects/deniedEntities 供入站校验。
+ * @param {string} [groupId] 群 scope；空则仅全局 deny
+ * @returns {PeerPoolView} 连接池视图
+ */
+export function loadPeerPoolView(groupId = '') {
+	const net = loadNetwork()
+	const deniedNodes = denyValuesForScope(groupId, 'node')
+	const deniedSubjects = denyValuesForScope(groupId, 'subject')
+	const deniedEntities = denyValuesForScope(groupId, 'entity')
+	/** @type {Map<string, string>} */
+	const hintSources = new Map()
+	for (const hint of net.hints)
+		if (!hintSources.has(hint.nodeHash))
+			hintSources.set(hint.nodeHash, hint.source)
+
+	return {
+		trustedPeers: net.trustedPeers,
+		explorePeers: net.explorePeers,
+		blockedPeers: deniedNodes,
+		deniedNodes,
+		deniedSubjects,
+		deniedEntities,
+		lastRosterAt: net.lastRosterAt,
+		hintSources,
+	}
+}
+
+/**
+ * @param {PeerPoolView} view 连接池视图
+ * @param {string} key nodeHash / pubKeyHash / entityHash 键
+ * @returns {boolean} 是否命中 denylist（按 scope 匹配）
+ */
+export function isPeerPoolKeyBlocked(view, key) {
+	const normalized = String(key || '').trim().toLowerCase()
+	if (!normalized) return false
+	if (view.deniedNodes.includes(normalized)) return true
+	if (view.deniedSubjects.includes(normalized)) return true
+	if (isEntityHash128(normalized) && view.deniedEntities.includes(normalized)) return true
+	return false
+}

package/node/personal_block.mjs

@@ -0,0 +1,286 @@
+/**
+ * 按实体的个人列表（Chat 与 Social 共享）。
+ * **block**：对外联邦公开拉黑（timeline block 事件 + personal_block 索引）；
+ * **hide**：纯本地隐藏（personal_hide.json，永不联邦）。
+ */
+import { parseEntityHash } from '../core/entity_id.mjs'
+import { isHex64, normalizeHex64 } from '../core/hexIds.mjs'
+import { isWritableLocalEntity } from '../entity/replica.mjs'
+
+import { isNodeInitialized, getEntityStore } from './instance.mjs'
+
+/** @typedef {'subject' | 'entity'} PersonalListScope */
+
+const HIDE_JSON = 'personal_hide.json'
+const MUTE_JSON = 'personal_mute.json'
+const BLOCK_INDEX_JSON = 'personal_block.json'
+
+/**
+ * @param {string} targetEntityHash 128 位十六进制
+ * @returns {Array<{ scope: PersonalListScope, value: string }>} 规范化条目
+ */
+export function entriesForTargetEntityHash(targetEntityHash) {
+	const parsed = parseEntityHash(targetEntityHash)
+	if (!parsed) return []
+	/** @type {Map<string, { scope: PersonalListScope, value: string }>} */
+	const byKey = new Map()
+	byKey.set(`entity:${parsed.entityHash}`, { scope: 'entity', value: parsed.entityHash })
+	if (isHex64(parsed.subjectHash))
+		byKey.set(`subject:${parsed.subjectHash}`, { scope: 'subject', value: parsed.subjectHash })
+	return [...byKey.values()]
+}
+
+/**
+ * @param {Array<{ scope?: string, value?: string }>} raw 原始条目
+ * @returns {Array<{ scope: PersonalListScope, value: string }>} 去重规范化
+ */
+export function normalizePersonalListEntries(raw) {
+	/** @type {Map<string, { scope: PersonalListScope, value: string }>} */
+	const byKey = new Map()
+	for (const entry of raw || []) {
+		const scope = String(entry?.scope || '').trim().toLowerCase()
+		const value = String(entry?.value || '').trim().toLowerCase()
+		if (scope === 'entity' && parseEntityHash(value))
+			byKey.set(`entity:${value}`, { scope: 'entity', value })
+		else if (scope === 'subject' && isHex64(normalizeHex64(value)))
+			byKey.set(`subject:${normalizeHex64(value)}`, { scope: 'subject', value: normalizeHex64(value) })
+	}
+	return [...byKey.values()]
+}
+
+/**
+ * @param {Array<{ scope: PersonalListScope, value: string }>} entries 列表
+ * @param {object} subject 待检主体
+ * @param {string} [subject.entityHash] 作者实体
+ * @param {string} [subject.pubKeyHash] 用户公钥哈希
+ * @param {string} [subject.subjectHash] 主体哈希
+ * @param {string} [subject.nodeHash] 节点哈希
+ * @returns {boolean} 是否命中列表
+ */
+export function matchesPersonalListEntries(entries, subject) {
+	const entity = String(subject?.entityHash || '').trim().toLowerCase()
+	const pk = normalizeHex64(subject?.pubKeyHash || subject?.subjectHash || '')
+	if (entity) {
+		for (const entry of entries)
+			if (entry.scope === 'entity' && entry.value === entity) return true
+		const parsed = parseEntityHash(entity)
+		if (parsed)
+			for (const entry of entries)
+				if (entry.scope === 'subject' && entry.value === parsed.subjectHash) return true
+	}
+	if (isHex64(pk))
+		for (const entry of entries)
+			if (entry.scope === 'subject' && entry.value === pk) return true
+	return false
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @returns {Promise<Array<{ scope: PersonalListScope, value: string }>>} 隐藏条目
+ */
+export async function loadPersonalHideEntries(viewerEntityHash) {
+	if (!isNodeInitialized()) return []
+	const data = await getEntityStore().readEntityJson(viewerEntityHash, HIDE_JSON)
+	return normalizePersonalListEntries(data?.hidden || [])
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @returns {Promise<Array<{ scope: PersonalListScope, value: string }>>} 静音条目
+ */
+export async function loadPersonalMuteEntries(viewerEntityHash) {
+	if (!isNodeInitialized()) return []
+	const data = await getEntityStore().readEntityJson(viewerEntityHash, MUTE_JSON)
+	return normalizePersonalListEntries(data?.muted || [])
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @returns {Promise<Array<{ scope: PersonalListScope, value: string }>>} 拉黑条目
+ */
+export async function loadPersonalBlockEntries(viewerEntityHash) {
+	if (!isNodeInitialized()) return []
+	const data = await getEntityStore().readEntityJson(viewerEntityHash, BLOCK_INDEX_JSON)
+	return normalizePersonalListEntries(data?.blocked || [])
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @param {object} subject 待检主体
+ * @returns {Promise<boolean>} 是否被隐藏
+ */
+export async function isHiddenBy(viewerEntityHash, subject) {
+	return matchesPersonalListEntries(await loadPersonalHideEntries(viewerEntityHash), subject)
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @param {object} subject 待检主体
+ * @returns {Promise<boolean>} 是否被拉黑
+ */
+export async function isBlockedBy(viewerEntityHash, subject) {
+	return matchesPersonalListEntries(await loadPersonalBlockEntries(viewerEntityHash), subject)
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @param {object} subject 待检主体
+ * @returns {Promise<boolean>} 是否应过滤
+ */
+export async function isFilteredByPersonalLists(viewerEntityHash, subject) {
+	if (!viewerEntityHash) return false
+	const [blocked, hidden, muted] = await Promise.all([
+		loadPersonalBlockEntries(viewerEntityHash),
+		loadPersonalHideEntries(viewerEntityHash),
+		loadPersonalMuteEntries(viewerEntityHash),
+	])
+	return matchesPersonalListEntries(blocked, subject)
+		|| matchesPersonalListEntries(hidden, subject)
+		|| matchesPersonalListEntries(muted, subject)
+}
+
+/**
+ * @param {string} viewerEntityHash 本地可写实体
+ * @param {string} targetEntityHash 目标
+ * @param {boolean} hide true=隐藏
+ * @returns {Promise<boolean>} 当前是否隐藏
+ */
+export async function setPersonalHidden(viewerEntityHash, targetEntityHash, hide) {
+	if (!isWritableLocalEntity(viewerEntityHash)) throw new Error('entity not writable on this replica')
+	const target = String(targetEntityHash || '').trim().toLowerCase()
+	if (!parseEntityHash(target)) throw new Error('invalid targetEntityHash')
+	const store = getEntityStore()
+	const current = normalizePersonalListEntries((await store.readEntityJson(viewerEntityHash, HIDE_JSON))?.hidden || [])
+	const addEntries = entriesForTargetEntityHash(target)
+	const addKeys = new Set(addEntries.map(e => `${e.scope}:${e.value}`))
+	const next = hide
+		? normalizePersonalListEntries([...current, ...addEntries])
+		: current.filter(entry => !addKeys.has(`${entry.scope}:${entry.value}`))
+	await store.writeEntityJson(viewerEntityHash, HIDE_JSON, { hidden: next })
+	return hide
+}
+
+/**
+ * @param {string} viewerEntityHash 本地可写实体
+ * @param {string} targetEntityHash 目标
+ * @param {boolean} mute true=静音
+ * @returns {Promise<boolean>} 当前是否静音
+ */
+export async function setPersonalMuted(viewerEntityHash, targetEntityHash, mute) {
+	if (!isWritableLocalEntity(viewerEntityHash)) throw new Error('entity not writable on this replica')
+	const target = String(targetEntityHash || '').trim().toLowerCase()
+	if (!parseEntityHash(target)) throw new Error('invalid targetEntityHash')
+	const store = getEntityStore()
+	const current = normalizePersonalListEntries((await store.readEntityJson(viewerEntityHash, MUTE_JSON))?.muted || [])
+	const addEntries = entriesForTargetEntityHash(target)
+	const addKeys = new Set(addEntries.map(e => `${e.scope}:${e.value}`))
+	const next = mute
+		? normalizePersonalListEntries([...current, ...addEntries])
+		: current.filter(entry => !addKeys.has(`${entry.scope}:${entry.value}`))
+	await store.writeEntityJson(viewerEntityHash, MUTE_JSON, { muted: next })
+	return mute
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @param {object} subject 待检主体
+ * @returns {Promise<boolean>} 是否被静音
+ */
+export async function isMutedBy(viewerEntityHash, subject) {
+	return matchesPersonalListEntries(await loadPersonalMuteEntries(viewerEntityHash), subject)
+}
+
+/**
+ * 从物化公开拉黑名单同步本地索引（真相源 = 时间线 blocked 集）。
+ * @param {string} viewerEntityHash 实体
+ * @param {string[]} blockedEntityHashes 物化 blocked entityHash 列表
+ * @returns {Promise<void>}
+ */
+export async function rebuildPersonalBlockIndex(viewerEntityHash, blockedEntityHashes) {
+	if (!isWritableLocalEntity(viewerEntityHash)) return
+	/** @type {Map<string, { scope: PersonalListScope, value: string }>} */
+	const byKey = new Map()
+	for (const raw of blockedEntityHashes || [])
+		for (const entry of entriesForTargetEntityHash(raw))
+			byKey.set(`${entry.scope}:${entry.value}`, entry)
+
+	await getEntityStore().writeEntityJson(viewerEntityHash, BLOCK_INDEX_JSON, {
+		blocked: [...byKey.values()],
+	})
+}
+
+/**
+ * 将 personal-lists API `{ entries }` 转为内存过滤集。
+ * @param {Array<{ scope?: string, kind?: string, value?: string }>} entries API 条目
+ * @returns {{ blockedEntityHashes: Set<string>, blockedSubjects: Set<string>, hiddenEntityHashes: Set<string>, hiddenSubjects: Set<string> }} 过滤集
+ */
+export function filterSetsFromPersonalListEntries(entries) {
+	/** @type {Set<string>} */
+	const blockedEntityHashes = new Set()
+	/** @type {Set<string>} */
+	const blockedSubjects = new Set()
+	/** @type {Set<string>} */
+	const hiddenEntityHashes = new Set()
+	/** @type {Set<string>} */
+	const hiddenSubjects = new Set()
+	/** @type {Set<string>} */
+	const mutedEntityHashes = new Set()
+	/** @type {Set<string>} */
+	const mutedSubjects = new Set()
+	for (const entry of entries || []) {
+		const kind = String(entry?.kind || '').trim().toLowerCase()
+		const scope = String(entry?.scope || '').trim().toLowerCase()
+		const value = String(entry?.value || '').trim().toLowerCase()
+		if (!value || (scope !== 'entity' && scope !== 'subject')) continue
+		if (kind === 'block')
+			if (scope === 'entity') blockedEntityHashes.add(value)
+			else blockedSubjects.add(value)
+
+		else if (kind === 'hide')
+			if (scope === 'entity') hiddenEntityHashes.add(value)
+			else hiddenSubjects.add(value)
+		else if (kind === 'mute')
+			if (scope === 'entity') mutedEntityHashes.add(value)
+			else mutedSubjects.add(value)
+
+	}
+	return { blockedEntityHashes, blockedSubjects, hiddenEntityHashes, hiddenSubjects, mutedEntityHashes, mutedSubjects }
+}
+
+/**
+ * @param {string} viewerEntityHash 观看者实体
+ * @returns {Promise<{ blockedEntityHashes: Set<string>, blockedSubjects: Set<string>, hiddenEntityHashes: Set<string>, hiddenSubjects: Set<string> }>} 过滤集
+ */
+export async function loadPersonalFilterSets(viewerEntityHash) {
+	if (!viewerEntityHash)
+		return filterSetsFromPersonalListEntries([])
+	const [blockedEntries, hiddenEntries, mutedEntries] = await Promise.all([
+		loadPersonalBlockEntries(viewerEntityHash),
+		loadPersonalHideEntries(viewerEntityHash),
+		loadPersonalMuteEntries(viewerEntityHash),
+	])
+	return filterSetsFromPersonalListEntries([
+		...blockedEntries.map(entry => ({ ...entry, kind: 'block' })),
+		...hiddenEntries.map(entry => ({ ...entry, kind: 'hide' })),
+		...mutedEntries.map(entry => ({ ...entry, kind: 'mute' })),
+	])
+}
+
+/**
+ * @param {object} filterSets loadPersonalFilterSets 结果
+ * @param {string} authorEntityHash 作者实体
+ * @returns {boolean} 是否应过滤
+ */
+export function isAuthorFilteredByPersonalSets(filterSets, authorEntityHash) {
+	const entity = String(authorEntityHash || '').trim().toLowerCase()
+	if (!entity) return false
+	if (filterSets.blockedEntityHashes.has(entity) || filterSets.hiddenEntityHashes.has(entity) || filterSets.mutedEntityHashes?.has(entity))
+		return true
+	const parsed = parseEntityHash(entity)
+	if (!parsed) return false
+	if (filterSets.blockedSubjects.has(parsed.subjectHash)
+		|| filterSets.hiddenSubjects.has(parsed.subjectHash)
+		|| filterSets.mutedSubjects?.has(parsed.subjectHash))
+		return true
+	return false
+}