@steve02081504/fount-p2p 0.0.0

package/reputation/math.mjs

@@ -0,0 +1,73 @@
+import reputationTunables from './tunables.json' with { type: 'json' }
+
+/**
+ * 主观信誉标量下界（§0.3）。
+ * @type {number}
+ */
+export const REP_MIN = -1
+/**
+ * 主观信誉标量上界（§0.3）。
+ * @type {number}
+ */
+export const REP_MAX = 1
+/** §0.1：`rep_max_eff = max(已链邻居最大信誉, ε)` */
+export const REP_MAX_EFF_EPS = 1e-12
+
+/**
+ * @param {number} x 任意标量
+ * @returns {number} clamp 到 [-1, 1]
+ */
+export function clampReputationScore(x) {
+	return Math.min(REP_MAX, Math.max(REP_MIN, x))
+}
+
+/**
+ * @param {{ byNodeHash?: Record<string, { score?: number }> }} data 信誉表
+ * @returns {number} `max(已链邻居最大信誉, ε)`（§0.1 `rep_max_eff`）
+ */
+export function computeRepMaxEff(data) {
+	let maxScore = /** @type {number | null} */ null
+	for (const nodeId of Object.keys(data.byNodeHash)) {
+		const score = Number(data.byNodeHash[nodeId]?.score)
+		if (!Number.isFinite(score)) continue
+		// rep_max_eff 仅由「可施加影响」的正信誉邻居定义，避免全负信誉集把分母压成异常值。
+		if (score <= 0) continue
+		maxScore = maxScore === null ? score : Math.max(maxScore, score)
+	}
+	return Math.max(maxScore === null ? 0 : clampReputationScore(maxScore), REP_MAX_EFF_EPS)
+}
+
+/**
+ * 不可验证 Slash 落地扣分（§0.1）。
+ * @param {number} claim 主张强度
+ * @param {number} repSender 发送方信誉
+ * @param {number} repMaxEff 分母
+ * @param {boolean} [verified] 是否可验证
+ * @param {typeof reputationTunables} [tunables] tunables
+ * @returns {number} 对目标的扣分幅度（正数）
+ */
+export function subjectiveSlashPenalty(claim, repSender, repMaxEff, verified = false, tunables = reputationTunables) {
+	const claimStrength = Number.isFinite(claim) ? claim : tunables.slashDefaultClaim
+	const senderInfluence = Math.max(0, Number.isFinite(repSender) ? repSender : 0)
+	return verified
+		? Math.abs(claimStrength) * tunables.slashVerifiedMultiplier
+		: Math.abs((claimStrength * senderInfluence) / repMaxEff)
+}
+
+/**
+ * §0.3 初值：`clamp(rep_local(intro) * reputationEdge)`。
+ *
+ * `repEdge` 缺省时退回 tunable `introducerSeedEdge`（抗女巫杠杆：边信任越低，
+ * 新成员从介绍者继承的初始信誉越少，邀请链批量灌号的收益越小）。
+ * @param {number} introRep 介绍者信誉
+ * @param {number} [repEdge] 边信任；省略则用 tunable 默认
+ * @param {typeof reputationTunables} [tunables] tunables
+ * @param {number} [powBonus=0] 入群 PoW 自愿封顶加成
+ * @returns {number} 新成员初值
+ */
+export function seedReputationFromIntro(introRep, repEdge, tunables = reputationTunables, powBonus = 0) {
+	const edge = Number.isFinite(repEdge) ? repEdge : tunables.introducerSeedEdge
+	const base = introRep * (Number.isFinite(edge) ? clampReputationScore(edge) : 1)
+	const bonus = Number.isFinite(powBonus) && powBonus > 0 ? powBonus : 0
+	return clampReputationScore(base + bonus)
+}

package/reputation/pick_score.mjs

@@ -0,0 +1,11 @@
+/**
+ * 纯函数：从已加载的 reputation 文件体计算节点全局分（无 setting_loader 依赖）。
+ * @param {object} repFile reputation.json 内容
+ * @param {string} nodeId 64 位十六进制 节点
+ * @returns {number} 信誉分
+ */
+export function pickNodeScoreFromReputation(repFile, nodeId) {
+	const row = repFile?.byNodeHash?.[nodeId]
+	if (!row) return 0
+	return Number(row.score ?? 0)
+}

package/reputation/relay_dedupe.mjs

@@ -0,0 +1,22 @@
+/**
+ * 联邦中继信誉加分去重（纯函数）。
+ */
+import reputationTunables from './tunables.json' with { type: 'json' }
+
+/**
+ * @param {Array<{ peerNodeHash: string, key: string, t: number }>} relayBumpSeen 已记录贡献
+ * @param {string} peerNodeHash 对端节点
+ * @param {string} dedupeKey 去重键
+ * @param {number} [now] 当前时间
+ * @param {number} [dedupeMs] 去重窗口
+ * @returns {boolean} 24h 内已计过分则为 true
+ */
+export function relayBumpIsDuplicate(relayBumpSeen, peerNodeHash, dedupeKey, now = Date.now(), dedupeMs = reputationTunables.relayBumpDedupeMs) {
+	if (!peerNodeHash) return true
+	const dedupe = dedupeKey || `conn:${peerNodeHash}`
+	return relayBumpSeen.some(
+		entry => entry.peerNodeHash === peerNodeHash
+			&& entry.key === dedupe
+			&& now - entry.t <= dedupeMs,
+	)
+}

package/reputation/tunables.json

@@ -0,0 +1,36 @@
+{
+	"wantUnknownWindowMs": 300000,
+	"wantUnknownThreshold": 3,
+	"penaltyUnknownWant": 0.12,
+	"penaltyMessageRate": 0.15,
+	"chunkStoreRepBump": 0.03,
+	"chunkFetchFailPenalty": 0.08,
+	"archiveServeMismatchPenalty": 0.08,
+	"relayRepBump": 0.02,
+	"defaultSlashAlertTtlMs": 86400000,
+	"maxRelayBumpSeen": 2000,
+	"relayBumpDedupeMs": 86400000,
+	"collusionLambda": 0.07,
+	"collusionDelta": 0.62,
+	"collusionMaxHop": 6,
+	"slashVerifiedMultiplier": 0.5,
+	"slashDefaultClaim": 0.2,
+	"slashVerifiedDefaultClaim": 0.35,
+	"slashUnverifiedDefaultClaim": 0.2,
+	"introducerSeedEdge": 0.5,
+	"recidivismMultiplierStep": 0.25,
+	"recidivismMax": 3,
+	"redemptionCreditPerStreakLevel": 0.08,
+	"inviteRedemptionCreditPerBad": 0.15,
+	"inviteBadEscalationStep": 0.5,
+	"inviteBadEscalationMax": 4,
+	"inviteHopBonusEvery": 2,
+	"inviteHopBonusMax": 4,
+	"inviteDeltaBoostPerBad": 0.05,
+	"inviteDeltaBoostMax": 0.3,
+	"baselineAlpha": 0.08,
+	"anomalyZThreshold": 2.8,
+	"quarantineTtlMs": 900000,
+	"quarantineTrustDamp": 0.35,
+	"baselineMinSamples": 6
+}

package/rooms/scoped_link.mjs

@@ -0,0 +1,185 @@
+import { advertiseTopic, subscribeTopic } from '../discovery/index.mjs'
+import { buildSignedAdvert, verifySignedAdvert } from '../link/handshake.mjs'
+import {
+	groupRendezvousTopic,
+	decryptSignalPacket,
+	encryptSignalPacket,
+	getLinkRegistry,
+} from '../transport/link_registry.mjs'
+
+/**
+ * 在指定 scope 与 roomSecret 下创建 link 层房间（discovery + registry 转发）。
+ * @param {object} opts 房间选项
+ * @param {string} opts.scope link registry scope（如 `group:{id}`）
+ * @param {string} opts.roomSecret 房间 rendezvous 密钥
+ * @param {(nodeHash: string) => boolean} [opts.allowNode] 是否允许与某 nodeHash 通信
+ * @returns {{ start: () => Promise<void>, leave: () => Promise<void>, makeAction: (name: string) => [(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void], onPeerJoin: (cb: (peerId: string) => void) => () => void, onPeerLeave: (cb: (peerId: string) => void) => () => void, getPeers: () => Record<string, true> }} 房间句柄
+ */
+export function createScopedLinkRoom(opts) {
+	const registry = getLinkRegistry()
+	const scope = String(opts.scope)
+	const topic = groupRendezvousTopic(opts.roomSecret)
+	const allowNode = typeof opts.allowNode === 'function' ? opts.allowNode : () => true
+	/** @type {Set<string>} */
+	const discoveredPeers = new Set()
+	/** @type {Set<string>} */
+	const announcedPeers = new Set()
+	/** @type {Set<(peerId: string) => void>} */
+	const joinListeners = new Set()
+	/** @type {Set<(peerId: string) => void>} */
+	const leaveListeners = new Set()
+	/** @type {Set<() => void>} */
+	const cleanups = new Set()
+	/** @type {Map<string, { handler: ((payload: unknown, peerId: string) => void) | null, backlog: Array<{ payload: unknown, peerId: string }> }>} */
+	const actionEntries = new Map()
+
+	/**
+	 * @returns {string[]} 当前已连接且通过 allowNode 过滤的 peer nodeHash 列表
+	 */
+	function activePeerIds() {
+		return [...discoveredPeers].filter(nodeHash => allowNode(nodeHash) && registry.getLink(nodeHash))
+	}
+
+	/**
+	 * @param {Set<(peerId: string) => void>} listeners 回调集合
+	 * @param {string} peerId 节点 hash
+	 * @returns {void}
+	 */
+	function emit(listeners, peerId) {
+		for (const listener of listeners)
+			try { listener(peerId) } catch { /* ignore */ }
+	}
+
+	/**
+	 * @param {string} peerId 节点 hash
+	 * @returns {void}
+	 */
+	function notePeerJoin(peerId) {
+		if (!peerId || announcedPeers.has(peerId)) return
+		announcedPeers.add(peerId)
+		emit(joinListeners, peerId)
+	}
+
+	/**
+	 * @param {string} peerId 节点 hash
+	 * @returns {void}
+	 */
+	function notePeerLeave(peerId) {
+		if (!peerId || !announcedPeers.has(peerId)) return
+		announcedPeers.delete(peerId)
+		emit(leaveListeners, peerId)
+	}
+
+	/**
+	 * @param {string} name action 名称
+	 * @returns {{ handler: ((payload: unknown, peerId: string) => void) | null, backlog: Array<{ payload: unknown, peerId: string }> }} action 槽（含待处理 backlog）
+	 */
+	function getActionEntry(name) {
+		const key = String(name)
+		if (!actionEntries.has(key))
+			actionEntries.set(key, { handler: null, backlog: [] })
+		return actionEntries.get(key)
+	}
+
+	return {
+		/**
+		 * @returns {Promise<void>}
+		 */
+		async start() {
+			await registry.ensureRuntime()
+			cleanups.add(registry.subscribeScope(scope, (senderNodeHash, envelope) => {
+				if (!allowNode(senderNodeHash)) return
+				const entry = actionEntries.get(String(envelope?.action || ''))
+				if (!entry) return
+				if (entry.handler) entry.handler(envelope.payload, senderNodeHash)
+				else entry.backlog.push({ payload: envelope.payload, peerId: senderNodeHash })
+			}))
+			cleanups.add(registry.onLinkUp(nodeHash => {
+				if (!discoveredPeers.has(nodeHash) || !allowNode(nodeHash)) return
+				notePeerJoin(nodeHash)
+			}))
+			cleanups.add(registry.onLinkDown(nodeHash => {
+				if (!discoveredPeers.has(nodeHash)) return
+				notePeerLeave(nodeHash)
+			}))
+			cleanups.add(await subscribeTopic(topic, async bytes => {
+				const packet = decryptSignalPacket(topic, bytes)
+				if (packet?.type !== 'advert' || !packet.body) return
+				const verifiedNodeHash = await verifySignedAdvert(topic, packet.body)
+				if (!verifiedNodeHash || !allowNode(verifiedNodeHash)) return
+				discoveredPeers.add(verifiedNodeHash)
+				await registry.ensureLinkToNode(verifiedNodeHash).catch(() => null)
+				if (registry.getLink(verifiedNodeHash)) notePeerJoin(verifiedNodeHash)
+			}))
+			cleanups.add(await advertiseTopic(topic, encryptSignalPacket(topic, {
+				type: 'advert',
+				body: await buildSignedAdvert(topic, Date.now(), registry.localIdentity),
+			})))
+			for (const peerId of activePeerIds())
+				notePeerJoin(peerId)
+		},
+		/**
+		 * @returns {Promise<void>}
+		 */
+		async leave() {
+			for (const cleanup of cleanups)
+				try { cleanup() } catch { /* ignore */ }
+			cleanups.clear()
+			for (const peerId of [...announcedPeers])
+				notePeerLeave(peerId)
+		},
+		/**
+		 * @param {string} name action 名称
+		 * @returns {[(payload: unknown, peerId?: string | string[] | null) => Promise<void>, (handler: (payload: unknown, peerId: string) => void) => void]} [send, onReceive] 发送与订阅元组
+		 */
+		makeAction(name) {
+			const actionName = String(name)
+			return [
+				async (payload, peerId = null) => {
+					if (Array.isArray(peerId)) {
+						await Promise.all(peerId.map(targetPeerId =>
+							registry.sendToNodeLink(targetPeerId, { scope, action: actionName, payload })))
+						return
+					}
+					if (peerId)
+						await registry.sendToNodeLink(peerId, { scope, action: actionName, payload })
+					else
+						await Promise.all(activePeerIds().map(targetPeerId =>
+							registry.sendToNodeLink(targetPeerId, { scope, action: actionName, payload })))
+				},
+				handler => {
+					const entry = getActionEntry(actionName)
+					entry.handler = handler
+					for (const pending of entry.backlog.splice(0))
+						handler(pending.payload, pending.peerId)
+				},
+			]
+		},
+		/**
+		 * @param {(peerId: string) => void} cb 新 peer 上线回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onPeerJoin(cb) {
+			joinListeners.add(cb)
+			for (const peerId of activePeerIds())
+				announcedPeers.add(peerId)
+			for (const peerId of announcedPeers)
+				try { cb(peerId) } catch { /* ignore */ }
+			return () => joinListeners.delete(cb)
+		},
+		/**
+		 * @param {(peerId: string) => void} cb peer 离线回调
+		 * @returns {() => void} 取消订阅
+		 */
+		onPeerLeave(cb) {
+			leaveListeners.add(cb)
+			return () => leaveListeners.delete(cb)
+		},
+		/**
+		 * @returns {Record<string, true>} 当前活跃 peer 的 nodeHash 集合
+		 */
+		getPeers() {
+			return Object.fromEntries(activePeerIds().map(peerId => [peerId, true]))
+		},
+	}
+}

package/schemas/discovery.mjs

@@ -0,0 +1,110 @@
+import { assertHex64, isHex64, isSignatureHex128, normalizeHex64 } from '../core/hexIds.mjs'
+import { isPlainObject } from '../wire/ingress.mjs'
+
+const MAX_DISCOVERY_ADS = 64
+
+/**
+ * @param {unknown} ad 单条 discovery 广告
+ * @returns {object | null} 白名单字段
+ */
+function sanitizeDiscoveryAdvertisement(ad) {
+	if (!isPlainObject(ad)) return null
+	const groupId = String(ad.groupId || '').trim()
+	const advertiserPubKeyHash = normalizeHex64(ad.advertiserPubKeyHash)
+	const signature = String(ad.signature || '').trim().toLowerCase()
+	if (!groupId || !isHex64(advertiserPubKeyHash) || !isSignatureHex128(signature)) return null
+	const advertiserNodeHash = normalizeHex64(ad.advertiserNodeHash)
+	const body = {
+		groupId,
+		title: String(ad.title || '').slice(0, 200),
+		blurb: String(ad.blurb || '').slice(0, 500),
+		advertiserPubKeyHash,
+		advertiserNodeHash: isHex64(advertiserNodeHash) ? advertiserNodeHash : String(ad.advertiserNodeHash || '').trim(),
+		observedAt: Number(ad.observedAt) || 0,
+		signature,
+	}
+	const memberCount = Number(ad.memberCount)
+	if (Number.isFinite(memberCount) && memberCount > 0)
+		body.memberCount = Math.floor(memberCount)
+	return body
+}
+
+/**
+ * @param {unknown} ads advertisements 数组
+ * @returns {object[]} 已清扫广告
+ */
+function sanitizeDiscoveryAdvertisements(ads) {
+	if (!Array.isArray(ads)) return []
+	return ads.slice(0, MAX_DISCOVERY_ADS).map(sanitizeDiscoveryAdvertisement).filter(Boolean)
+}
+
+/**
+ * @param {unknown} nodeHash 节点 hash
+ * @returns {string} 规范化 hex64
+ */
+export function assertDiscoveryNodeHash(nodeHash) {
+	return assertHex64(nodeHash, 'discovery.nodeHash')
+}
+
+/**
+ * @param {unknown} requestId 请求 id
+ * @returns {string} 非空 trimmed 字符串
+ */
+export function assertDiscoveryRequestId(requestId) {
+	const id = String(requestId ?? '').trim()
+	if (!id) throw new Error('discovery.requestId required')
+	return id
+}
+
+/**
+ * @param {unknown} payload 载荷
+ * @returns {{ nodeHash: string, advertisements: object[] } | null} 解析结果
+ */
+export function parseDiscoveryAnnounce(payload) {
+	if (!isPlainObject(payload)) return null
+	try {
+		return {
+			nodeHash: assertDiscoveryNodeHash(payload.nodeHash),
+			advertisements: sanitizeDiscoveryAdvertisements(payload.advertisements),
+		}
+	}
+	catch {
+		return null
+	}
+}
+
+/**
+ * @param {unknown} payload 载荷
+ * @returns {{ nodeHash: string, requestId: string, limit: number } | null} 解析结果
+ */
+export function parseDiscoveryQuery(payload) {
+	if (!isPlainObject(payload)) return null
+	try {
+		return {
+			nodeHash: assertDiscoveryNodeHash(payload.nodeHash),
+			requestId: assertDiscoveryRequestId(payload.requestId),
+			limit: Math.min(64, Math.max(1, Number(payload.limit) || 32)),
+		}
+	}
+	catch {
+		return null
+	}
+}
+
+/**
+ * @param {unknown} payload 载荷
+ * @returns {{ requestId: string, nodeHash: string, advertisements: object[] } | null} 解析结果
+ */
+export function parseDiscoveryQueryResponse(payload) {
+	if (!isPlainObject(payload)) return null
+	try {
+		return {
+			requestId: assertDiscoveryRequestId(payload.requestId),
+			nodeHash: assertDiscoveryNodeHash(payload.nodeHash),
+			advertisements: sanitizeDiscoveryAdvertisements(payload.advertisements),
+		}
+	}
+	catch {
+		return null
+	}
+}

package/schemas/federation_pull.mjs

@@ -0,0 +1,102 @@
+/**
+ * 联邦补拉 attestation / HPKE 响应 wire 解析（无 attestation/envelope 即丢弃）。
+ */
+import { isHex64, isSignatureHex128, normalizeHex64 } from '../core/hexIds.mjs'
+import { EVENT_ID_HEX } from '../dag/index.mjs'
+import { isPlainObject } from '../wire/ingress.mjs'
+
+/** @typedef {{ requesterPubKeyHash: string, groupId: string, requestId: string, timestamp: number, wantIds?: string[], signature: string }} PullAttestation */
+
+const ENVELOPE_BLOB_MIN_LEN = 2
+
+/**
+ * @param {unknown} value 密文字段
+ * @returns {boolean} 是否像合法 ECIES blob 段
+ */
+function isEnvelopeBlob(value) {
+	return String(value ?? '').trim().length >= ENVELOPE_BLOB_MIN_LEN
+}
+
+/**
+ * @param {unknown} attestation 载荷 attestation 字段
+ * @returns {PullAttestation | null} 解析结果
+ */
+export function parsePullAttestation(attestation) {
+	if (!isPlainObject(attestation)) return null
+	const requesterPubKeyHash = normalizeHex64(attestation.requesterPubKeyHash)
+	const groupId = String(attestation.groupId || '').trim()
+	const requestId = String(attestation.requestId || '').trim()
+	const timestamp = Number(attestation.timestamp)
+	const signature = String(attestation.signature || '').trim().toLowerCase()
+	if (!isHex64(requesterPubKeyHash) || !groupId || !Number.isFinite(timestamp) || !isSignatureHex128(signature))
+		return null
+	const wantIds = Array.isArray(attestation.wantIds)
+		? [...new Set(attestation.wantIds.map(id => String(id).trim().toLowerCase()).filter(id => EVENT_ID_HEX.test(id)))]
+		: undefined
+	return {
+		requesterPubKeyHash,
+		groupId,
+		requestId,
+		timestamp,
+		wantIds,
+		signature,
+	}
+}
+
+/**
+ * @param {unknown} envelope 响应 envelope
+ * @returns {{ requestId: string, requesterPubKeyHash: string, requesterNodeHash: string, ephemPub: string, iv: string, ciphertext: string, authTag: string } | null} 解析结果
+ */
+export function parsePullResponseEnvelope(envelope) {
+	if (!isPlainObject(envelope)) return null
+	const requestId = String(envelope.requestId || '').trim()
+	const requesterPubKeyHash = normalizeHex64(envelope.requesterPubKeyHash)
+	const requesterNodeHash = String(envelope.requesterNodeHash || '').trim()
+	const ephemPub = String(envelope.ephemPub || '').trim()
+	const iv = String(envelope.iv || '').trim()
+	const ciphertext = String(envelope.ciphertext || '').trim()
+	const authTag = String(envelope.authTag || '').trim()
+	if (!requestId || !isHex64(requesterPubKeyHash) || !requesterNodeHash) return null
+	if (!isEnvelopeBlob(ephemPub) || !isEnvelopeBlob(iv) || !isEnvelopeBlob(ciphertext) || !isEnvelopeBlob(authTag))
+		return null
+	return {
+		requestId,
+		requesterPubKeyHash,
+		requesterNodeHash,
+		ephemPub,
+		iv,
+		ciphertext,
+		authTag,
+	}
+}
+
+/**
+ * @param {unknown} data 入群快照请求载荷
+ * @returns {object | null} 解析结果
+ */
+export function parseJoinSnapshotRequest(data) {
+	if (!isPlainObject(data)) return null
+	const requestId = String(data.requestId || '').trim()
+	const requesterNodeHash = String(data.requesterNodeHash || '').trim()
+	const groupId = String(data.groupId || '').trim()
+	const attestation = parsePullAttestation(data.attestation)
+	if (!requestId || !requesterNodeHash || !groupId || !attestation) return null
+	if (attestation.groupId !== groupId || attestation.requestId !== requestId) return null
+	const tipsHash = String(data.tipsHash || '').trim()
+	return {
+		requestId,
+		requesterNodeHash,
+		requesterPubKeyHash: attestation.requesterPubKeyHash,
+		groupId,
+		tipsHash: tipsHash ? tipsHash.toLowerCase() : undefined,
+		attestation,
+	}
+}
+
+/**
+ * @param {unknown} data 入群快照响应载荷
+ * @returns {object | null} 解析结果
+ */
+export function parseJoinSnapshotResponse(data) {
+	return parsePullResponseEnvelope(data)
+}

package/schemas/mailbox.mjs

@@ -0,0 +1,37 @@
+import { normalizeHex64, HEX_ID_64 } from '../core/hexIds.mjs'
+
+/**
+ * @typedef {{ ok: true, value: string }} MailboxWireOk
+ * @typedef {{ ok: false, code: string, field: string }} MailboxWireErr
+ * @typedef {MailboxWireOk | MailboxWireErr} MailboxWireResult
+ */
+
+/**
+ * @typedef {{ ok: true, value: object }} MailboxRecordShapeOk
+ * @typedef {MailboxWireErr} MailboxRecordShapeErr
+ * @typedef {MailboxRecordShapeOk | MailboxRecordShapeErr} MailboxRecordShapeResult
+ */
+
+/**
+ * @param {unknown} value 收件人 pubKeyHash
+ * @returns {MailboxWireResult} 规范化 hex64 或结构化错误
+ */
+export function assertMailboxPubKeyHash(value) {
+	const normalized = normalizeHex64(value)
+	if (!HEX_ID_64.test(normalized))
+		return { ok: false, code: 'invalid_hex64', field: 'toPubKeyHash' }
+	return { ok: true, value: normalized }
+}
+
+/**
+ * @param {unknown} record mailbox 记录
+ * @returns {MailboxRecordShapeResult} 已校验的 record 或结构化错误
+ */
+export function assertMailboxRecordShape(record) {
+	if (!record || typeof record !== 'object')
+		return { ok: false, code: 'required', field: 'record' }
+	const pubKey = assertMailboxPubKeyHash(record.toPubKeyHash)
+	if (!pubKey.ok)
+		return { ok: false, code: pubKey.code, field: 'record.toPubKeyHash' }
+	return { ok: true, value: record }
+}

package/schemas/remote_event.mjs

@@ -0,0 +1,17 @@
+import { assertHex64 } from '../core/hexIds.mjs'
+
+/**
+ * 远程入站事件形状校验（仅 federation / P2P 路径调用）。
+ * @param {object} event DAG 事件
+ * @returns {void}
+ */
+export function validateRemoteEventShape(event) {
+	if (!event?.type || typeof event.type !== 'string')
+		throw new Error('remote event: type required')
+	assertHex64(event.id, 'remote event.id')
+	if (!Array.isArray(event.prev_event_ids))
+		throw new Error('remote event: prev_event_ids must be array')
+	for (const parentId of event.prev_event_ids)
+		assertHex64(parentId, 'remote event.prev_event_id')
+	assertHex64(event.sender, 'remote event.sender')
+}

package/timeline/append_core.mjs

@@ -0,0 +1,54 @@
+import { Buffer } from 'node:buffer'
+
+import { nextHlc } from '../core/hlc.mjs'
+import { publicKeyFromSeed, sign } from '../crypto/crypto.mjs'
+import {
+	computeEventId,
+	eventBodyForSign,
+	signPayloadBytes,
+	sortedPrevEventIds,
+} from '../dag/index.mjs'
+import { computeDagTipIdsFromEvents } from '../governance/branch.mjs'
+
+/**
+ * 为追加事件计算 HLC 与 DAG 前驱（chat 群与 social 时间线共用）。
+ * @param {object[]} previous 已有事件
+ * @param {object} event 待追加事件
+ * @param {{ multiTip?: boolean }} [opts] chat 在多 tip 时连接全部 tip
+ * @returns {{ hlc: object, prev_event_ids: string[], last: object | undefined }} HLC、前驱与末条事件
+ */
+export function computeAppendHlcAndPrev(previous, event, opts = {}) {
+	const last = previous[previous.length - 1]
+	const hlc = nextHlc(last?.hlc, event.timestamp ?? Date.now())
+	const tips = computeDagTipIdsFromEvents(previous)
+	let prev_event_ids
+	if (event.prev_event_ids?.length)
+		prev_event_ids = sortedPrevEventIds(event.prev_event_ids)
+	else if (opts.multiTip && tips.length > 1)
+		prev_event_ids = sortedPrevEventIds(tips)
+	else if (tips.length)
+		prev_event_ids = sortedPrevEventIds(tips)
+	else if (last?.id)
+		prev_event_ids = [last.id]
+	else
+		prev_event_ids = []
+	return { hlc, prev_event_ids, last }
+}
+
+/**
+ * 使用 eventBodyForSign 规范签名并返回完整事件（social 时间线）。
+ * @param {object} base 事件基体（含 type/groupId/sender/hlc/prev_event_ids/content/node_id）
+ * @param {Uint8Array} secretKey 签名密钥
+ * @returns {object} 签名后事件
+ */
+export async function signTimelineEvent(base, secretKey) {
+	const body = eventBodyForSign(base)
+	const id = computeEventId(body)
+	const signature = await sign(signPayloadBytes(body), secretKey)
+	return {
+		...base,
+		id,
+		signature: Buffer.from(signature).toString('hex'),
+		senderPubKey: Buffer.from(publicKeyFromSeed(secretKey)).toString('hex'),
+	}
+}

package/timeline/materialize_runner.mjs

@@ -0,0 +1,26 @@
+import { topologicalCanonicalOrder } from '../dag/index.mjs'
+
+/**
+ * 拓扑序后按 reducer 表折叠事件列表。
+ * @param {object[]} events 原始事件
+ * @param {Record<string, (state: object, event: object) => object>} reducers 事件类型 → reducer
+ * @param {() => object} createInitialState 初始状态工厂
+ * @returns {{ state: object, order: string[] }} 物化结果与拓扑序
+ */
+export function materializeFromEvents(events, reducers, createInitialState) {
+	const order = topologicalCanonicalOrder(events.map(event => ({
+		id: event.id,
+		prev_event_ids: event.prev_event_ids,
+		hlc: event.hlc,
+		node_id: event.node_id,
+	})))
+	const byId = new Map(events.map(event => [event.id, event]))
+	let state = createInitialState()
+	for (const eventId of order) {
+		const event = byId.get(eventId)
+		if (!event) continue
+		const reducer = reducers[event.type]
+		if (reducer) state = reducer(state, event)
+	}
+	return { state, order }
+}