@steve02081504/fount-p2p 0.0.30 → 0.0.32

package/sim/AGENTS.md

@@ -0,0 +1,29 @@
+---
+description: P2P tunables simulation / co-evolution harness — fidelity boundary between reused real logic and heuristic proxy environment
+globs: sim/**
+alwaysApply: false
+---
+
+# P2P Sim Harness Guide
+
+In-process co-evolution of **tunables** (`*.tunables.json`) against an **attack genome**, scored by `metrics.mjs`. Search proxy — **not** wire-protocol replay.
+
+## Fidelity boundary
+
+- **Reused verbatim** (import real decision functions; do not re-model): `reputation/engine.mjs`, `reputation/math.mjs`, `sim/social_reputation.mjs` (`*Pure`), `trust_graph/engine.mjs` (`pickTop`), `trust_graph/resolve.mjs`, `governance/join_pow.mjs`.
+- **Tunables source:** `tunables_bundle.mjs` loads in-package `*.tunables.json` plus `sim/reputation_social.tunables.json`. Write social tunables back via `cli.mjs mine --social-tunables PATH` (`apply.mjs`).
+- **`PARAM_SPACE` ↔ defaults:** every `PARAM_SPACE` key must exist in `loadDefaultTunables()`; clear both sides when deleting a key.
+- **`socialRepHideThreshold`:** hide when `score < threshold`. Default `0` (suppress negatives only). Raise the threshold to raise `falsePositiveRate` — never use a negative threshold for "stricter".
+- **Heuristic proxy** (not the real path): `model.mjs`, `discovery.mjs`, `transport.mjs`, `integrity.mjs` — analytical "params → defense" only.
+- **Mesh-first:** explore slots and cold-start join are mandatory; fanout/trust stay separate from link presence. Policy: [docs/mesh.md](../docs/mesh.md). Wiring: [cold_start.md](cold_start.md).
+
+## Anti-drift
+
+- Do not hand-copy runtime constants. RTC budget from `transport/rtc_connection_budget.mjs`. `EXPLORE_MAX_PER_SOURCE` mirrors `peer_pool.mjs` but stays local (importing `peer_pool` pulls fs) — `test/fidelity.test.mjs` asserts equality.
+- Signaling source names (`DEFAULT_SIGNALING_SOURCES`) must be real provider ids (`lan` / `nostr` / `bt`). No `tracker` provider.
+- New sim constants that shadow real ones need a matching assertion in `fidelity.test.mjs`.
+
+## Determinism
+
+- Seeded via `rng.mjs` (`createRng`). `runSimulation(...)` must be pure — `fidelity.test.mjs` asserts serial == parallel == batched snapshots. Use `simulationContext.now` (virtual clock, +60s/round); no wall-clock or unseeded RNG.
+- Round state object is `simulationContext` (not `ctx`); `buildWorld` returns `{ simulationContext }`.

package/sim/admission.mjs

@@ -0,0 +1,56 @@
+/**
+ * 入群 PoW 成本模型：算力预算限速 Sybil/洗白造号。
+ */
+import { expectedJoinPowHashes, powVoluntaryBonus } from '../governance/join_pow.mjs'
+
+/** 每回合可消耗的期望哈希预算（相对 2^16 基准） */
+const HASH_BUDGET_PER_ROUND = 65536
+
+/**
+ * @param {import('./tunables_bundle.mjs').TunablesBundle['admission']} admission admission tunables
+ * @returns {number} 准入 floor bit
+ */
+export function resolvePowFloorBits(admission) {
+	return Math.max(1, Math.floor(Number(admission?.powFloorBits ?? admission?.powDifficultyBits ?? 18)))
+}
+
+/**
+ * @param {number} achievedBits 解达成 bit
+ * @param {import('./tunables_bundle.mjs').TunablesBundle['admission']} admission admission tunables
+ * @returns {number} 自愿封顶信誉加成
+ */
+export function simPowVoluntaryBonus(achievedBits, admission) {
+	return powVoluntaryBonus(achievedBits, resolvePowFloorBits(admission), admission)
+}
+
+/**
+ * @param {number} difficultyBits PoW floor bit
+ * @returns {number} 造一个新身份期望回合成本
+ */
+export function roundsPerIdentity(difficultyBits) {
+	const expected = expectedJoinPowHashes(difficultyBits)
+	return Math.max(1, expected / HASH_BUDGET_PER_ROUND)
+}
+
+/**
+ * @param {number} requested 请求数量
+ * @param {number} difficultyBits PoW 难度
+ * @param {number} rounds 仿真总回合
+ * @returns {number} 预算内可生成的恶意身份数
+ */
+export function capMaliciousByPowBudget(requested, difficultyBits, rounds) {
+	const cost = roundsPerIdentity(difficultyBits)
+	const budget = Math.max(1, Math.floor(rounds / cost))
+	return Math.min(requested, budget)
+}
+
+/**
+ * @param {number} difficultyBits PoW 难度
+ * @param {number} rounds 回合数
+ * @returns {number} 诚实新人入群延迟惩罚 0..1（越高=越慢）
+ */
+export function honestJoinDelayPenalty(difficultyBits, rounds) {
+	const cost = roundsPerIdentity(difficultyBits)
+	const delay = cost / Math.max(1, rounds * 0.25)
+	return Math.min(1, delay)
+}

package/sim/anomaly.mjs

@@ -0,0 +1,39 @@
+/**
+ * 仿真器中的本地可逆异常隔离（映射生产 reputation_engine 纯函数）。
+ */
+import {
+	isQuarantinedPure,
+	observeBehaviorSamplePure,
+} from '../reputation/engine.mjs'
+
+/**
+ * @param {import('../node/reputation_store.mjs').ReputationFile} reputation 观察者信誉表
+ * @param {string} peerId 对端 nodeHash
+ * @param {number} sample 行为样本
+ * @param {number} now 当前时间
+ * @param {import('../reputation/tunables.json')} tunables reputation tunables
+ * @returns {boolean} 是否触发隔离
+ */
+export function simObservePeerBehavior(reputation, peerId, sample, now, tunables) {
+	return observeBehaviorSamplePure(reputation, peerId, sample, now, tunables).anomaly
+}
+
+/**
+ * @param {import('../node/reputation_store.mjs').ReputationFile} reputation 观察者信誉表
+ * @param {string} peerId 对端 nodeHash
+ * @param {number} now 当前时间
+ * @returns {boolean} 是否隔离中
+ */
+export function simIsPeerQuarantined(reputation, peerId, now) {
+	return isQuarantinedPure(reputation, peerId, now)
+}
+
+/**
+ * @param {number} discoveryReach 发现可达 0..1
+ * @param {() => number} rng 随机源
+ * @returns {boolean} 攻击是否触达该观察者
+ */
+export function attackReachesObserver(discoveryReach, rng) {
+	const reach = Math.max(0, Math.min(1, discoveryReach))
+	return rng() < 0.15 + reach * 0.85
+}

package/sim/apply.mjs

@@ -0,0 +1,77 @@
+/**
+ * 按模块写回 tunables JSON。
+ */
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { normalizeBundle, sanitizeBundle } from './space.mjs'
+
+/** @typedef {import('./tunables_bundle.mjs').TunablesBundle} TunablesBundle */
+
+/** @type {Record<Exclude<keyof TunablesBundle, 'social'>, URL>} */
+const PACKAGE_MODULE_URLS = {
+	reputation: new URL('../reputation/tunables.json', import.meta.url),
+	trustGraph: new URL('../trust_graph/tunables.json', import.meta.url),
+	mailbox: new URL('../mailbox/tunables.json', import.meta.url),
+	archive: new URL('../dag/tunables.json', import.meta.url),
+	admission: new URL('../governance/tunables.json', import.meta.url),
+}
+
+/**
+ * @param {TunablesBundle} bundle 完整 tunables
+ * @returns {TunablesBundle} 写盘前规整后的 bundle
+ */
+export function prepareBundleForApply(bundle) {
+	return sanitizeBundle(normalizeBundle(bundle))
+}
+
+/**
+ * @param {string} socialTunablesPath 外部 social shell 的 reputation_social.tunables.json 绝对或相对路径
+ * @returns {string} 规范化绝对路径
+ */
+export function resolveSocialTunablesPath(socialTunablesPath) {
+	const raw = String(socialTunablesPath ?? '').trim()
+	if (!raw) throw new Error('socialTunablesPath required to write social tunables')
+	return path.resolve(raw)
+}
+
+/**
+ * @param {keyof TunablesBundle} module 模块键
+ * @param {Record<string, unknown>} data JSON 内容
+ * @param {string} [socialTunablesPath] social 模块写入路径（module === 'social' 时必填）
+ * @returns {Promise<string>} 写入路径
+ */
+export async function writeModuleTunables(module, data, socialTunablesPath) {
+	const filePath = module === 'social'
+		? resolveSocialTunablesPath(socialTunablesPath)
+		: fileURLToPath(PACKAGE_MODULE_URLS[module])
+	await writeFile(filePath, `${JSON.stringify(data, null, '\t')}\n`, 'utf8')
+	return filePath
+}
+
+/**
+ * @param {TunablesBundle} bundle 完整 tunables
+ * @param {{ socialTunablesPath: string }} paths 外部模块路径（social 写回 shell 侧 JSON）
+ * @returns {Promise<string[]>} 各模块 JSON 写入路径
+ */
+export async function applyTunablesBundle(bundle, paths) {
+	const socialPath = resolveSocialTunablesPath(paths?.socialTunablesPath)
+	const ready = prepareBundleForApply(bundle)
+	const written = []
+	written.push(await writeModuleTunables('reputation', ready.reputation))
+	written.push(await writeModuleTunables('trustGraph', ready.trustGraph))
+	written.push(await writeModuleTunables('social', ready.social, socialPath))
+	written.push(await writeModuleTunables('mailbox', ready.mailbox))
+	written.push(await writeModuleTunables('archive', ready.archive))
+	written.push(await writeModuleTunables('admission', ready.admission))
+	return written
+}
+
+/**
+ * @param {string} [dir] sim 目录（默认本模块目录）
+ * @returns {string} results 子目录绝对路径
+ */
+export function resultsDirFromSim(dir = path.dirname(fileURLToPath(import.meta.url))) {
+	return path.join(dir, 'results')
+}

package/sim/attack_space.mjs

@@ -0,0 +1,113 @@
+/**
+ * 攻击者可进化基因（与 space.mjs 采样器共用 latent 语义）。
+ */
+import { createRng } from './rng.mjs'
+import { normalizeParam, sampleParam } from './space.mjs'
+import { loadDefaultTunables } from './tunables_bundle.mjs'
+
+/** @typedef {import('./attacks.mjs').AttackKind} AttackKind */
+
+/**
+ * @typedef {{
+ *   global: { activationRate: number, burstSize: number, targetBiasHighRep: number, eclipseFocus: number },
+ *   byAttack: Partial<Record<AttackKind, { activationRate?: number, burstSize?: number, collusionAllyRate?: number, sleeperTurnFrac?: number, hintWeightMul?: number }>>,
+ * }} AttackGenome
+ */
+
+/** @type {import('./space.mjs').ParamSpec[]} */
+const GLOBAL_ATTACK_SPECS = [
+	{ module: 'reputation', key: 'relayRepBump', kind: 'unit' }, // reuse kind; values remapped below
+]
+
+const DEFAULT_GENOME = Object.freeze({
+	global: {
+		activationRate: 0.55,
+		burstSize: 4,
+		targetBiasHighRep: 0.35,
+		eclipseFocus: 0.65,
+	},
+	byAttack: {},
+})
+
+/**
+ * @param {() => number} rng 随机源
+ * @returns {AttackGenome} 随机攻击基因组
+ */
+export function randomAttackGenome(rng) {
+	return {
+		global: {
+			activationRate: 0.2 + rng() * 0.75,
+			burstSize: 1 + Math.floor(rng() * 8),
+			targetBiasHighRep: rng() * 0.9,
+			eclipseFocus: 0.3 + rng() * 0.65,
+		},
+		byAttack: {},
+	}
+}
+
+/**
+ * @param {AttackGenome} parent 父代
+ * @param {number} seed 种子
+ * @returns {AttackGenome} 变异子代
+ */
+export function mutateAttackGenome(parent, seed) {
+	const rng = createRng(seed)
+	const child = structuredClone(parent)
+	if (rng() < 0.4) child.global.activationRate = Math.max(0.05, Math.min(0.98, child.global.activationRate + (rng() - 0.5) * 0.2))
+	if (rng() < 0.35) child.global.burstSize = Math.max(1, Math.min(12, child.global.burstSize + Math.floor((rng() - 0.5) * 4)))
+	if (rng() < 0.3) child.global.targetBiasHighRep = Math.max(0, Math.min(1, child.global.targetBiasHighRep + (rng() - 0.5) * 0.25))
+	if (rng() < 0.3) child.global.eclipseFocus = Math.max(0.1, Math.min(1, child.global.eclipseFocus + (rng() - 0.5) * 0.25))
+	return child
+}
+
+/**
+ * @param {AttackKind} attack 攻击类型
+ * @param {AttackGenome} genome 基因组
+ * @returns {{ activationRate: number, burstSize: number, targetBiasHighRep: number, eclipseFocus: number, collusionAllyRate: number, sleeperTurnFrac: number, hintWeightMul: number }} 有效参数
+ */
+export function resolveAttackParams(attack, genome) {
+	const g = genome.global
+	const row = genome.byAttack[attack] ?? {}
+	return {
+		activationRate: row.activationRate ?? g.activationRate,
+		burstSize: Math.max(1, Math.floor(row.burstSize ?? g.burstSize)),
+		targetBiasHighRep: g.targetBiasHighRep,
+		eclipseFocus: g.eclipseFocus,
+		collusionAllyRate: row.collusionAllyRate ?? 0.25,
+		sleeperTurnFrac: row.sleeperTurnFrac ?? 0.35,
+		hintWeightMul: row.hintWeightMul ?? 3,
+	}
+}
+
+/**
+ * @param {AttackGenome | undefined} genome 基因组
+ * @returns {AttackGenome} 默认补齐
+ */
+export function normalizeAttackGenome(genome) {
+	if (!genome) return structuredClone(DEFAULT_GENOME)
+	return {
+		global: { ...DEFAULT_GENOME.global, ...genome.global },
+		byAttack: { ...genome.byAttack },
+	}
+}
+
+/** 名人堂容量 */
+export const ATTACK_HOF_SIZE = 6
+
+/**
+ * @param {Array<{ genome: AttackGenome, fitness: number }>} hall 名人堂
+ * @param {AttackGenome} genome 候选
+ * @param {number} fitness 适应度
+ * @returns {Array<{ genome: AttackGenome, fitness: number }>} 更新后名人堂
+ */
+export function updateAttackHallOfFame(hall, genome, fitness) {
+	const next = [...hall, { genome: structuredClone(genome), fitness }]
+	next.sort((a, b) => b.fitness - a.fitness)
+	return next.slice(0, ATTACK_HOF_SIZE)
+}
+
+// silence unused import warning from eslint if any
+void GLOBAL_ATTACK_SPECS
+void loadDefaultTunables
+void normalizeParam
+void sampleParam