@bolloon/bolloon-agent 0.4.31 → 0.4.32

package/dist/electron-build/agents/network-pulse.js

@@ -11,6 +11,10 @@
  *   · 快照过期 → `stale` (不许伪装实时); 观察层不可用 → `unavailable`
  *   · 类别小于隐私阈值 → 合并进 other
  *   · 事件数 / 时间窗 / capability 数都有上限
+ *   · **冻结形状 `confirmed_activity`** (2026-09-22): 公开页面要能列出「哪个任务 · 什么状态 ·
+ *     哪个块 · 多少确认」, 而不是只有数字 —— 数据源优先 P5 链上索引, 不可用时退回脉冲事件并
+ *     用 `confirmed_activity_source` 标注; 标识一律 sha256 短写 (前 8 位), 绝不落 taskKey /
+ *     taskId / txHash 原文; 不够确认门槛的行只报 observed, 不冒充 confirmed。
  *
  * 借鉴 (只借产品与工程思想, 不借 Go/Postgres/API 项目):
  *   EigenFlux 的 "注册总量 / 当前活跃 / 最近出现" 时间窗统计、服务端生成匿名活动文本、
@@ -50,7 +54,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FORBIDDEN_PUBLIC_KEYS = exports.MAX_AGENT_SITES = exports.pulseDir = exports.NETWORK_EVENT_TYPES = exports.PULSE_LIMITS = void 0;
+exports.FORBIDDEN_PUBLIC_KEYS = exports.CHAIN_LABELS = exports.PUBLIC_MAINNET_CHAIN_ID = exports.PUBLIC_TESTNET_CHAIN_ID = exports.PULSE_EVENT_ACTIVITY = exports.CHAIN_EVENT_ACTIVITY = exports.CONFIRMED_ACTIVITY_LIMIT = exports.MAX_AGENT_SITES = exports.pulseDir = exports.NETWORK_EVENT_TYPES = exports.PULSE_LIMITS = void 0;
 exports.nodeDigest = nodeDigest;
 exports.capabilityGroup = capabilityGroup;
 exports.bucketOf = bucketOf;
@@ -59,6 +63,19 @@ exports.renderActivityText = renderActivityText;
 exports.normalizeIpns = normalizeIpns;
 exports.readAgentSites = readAgentSites;
 exports.emitTradePulse = emitTradePulse;
+exports.anonShortRef = anonShortRef;
+exports.isoSeconds = isoSeconds;
+exports.normalizeActivityGates = normalizeActivityGates;
+exports.finalityFromConfirmations = finalityFromConfirmations;
+exports.buildConfirmedActivityFromIndex = buildConfirmedActivityFromIndex;
+exports.buildConfirmedActivityFromEvents = buildConfirmedActivityFromEvents;
+exports.confirmedActivityFromEvents = confirmedActivityFromEvents;
+exports.resolveConfirmedActivity = resolveConfirmedActivity;
+exports.chainLabelOf = chainLabelOf;
+exports.isPublicChainId = isPublicChainId;
+exports.summarizeActivityRows = summarizeActivityRows;
+exports.buildChainIdScope = buildChainIdScope;
+exports.snapshotConsistencyIssues = snapshotConsistencyIssues;
 exports.computeSnapshot = computeSnapshot;
 exports.getNetworkPulse = getNetworkPulse;
 exports.snapshotStatus = snapshotStatus;
@@ -71,6 +88,8 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
+// 确认数门槛来自 chain-config (单一实现; 默认 confirmed=1 / finalized=12) —— 只借常量, 不借 RPC
+const chain_config_js_1 = require("./chain/chain-config.js");
 // ── 常量 (上限 + 时间边界) ─────────────────────────────────────────────────
 exports.PULSE_LIMITS = {
     /** 最多留多少条事件 (超出丢最旧) */
@@ -89,6 +108,8 @@ exports.PULSE_LIMITS = {
     snapshotTtlMs: 30 * 1000,
     /** 活动流最多几条 */
     maxActivity: 8,
+    /** confirmed_activity (冻结形状的真实活动行) 上限 */
+    maxConfirmedActivity: 25,
 };
 /** 事件类型白名单 —— 只允许这些进统计 (其余一律丢弃) */
 exports.NETWORK_EVENT_TYPES = [
@@ -290,10 +311,404 @@ async function emitTradePulse(before, after, h) {
         /* 统计失败绝不影响交易主路径 */
     }
 }
+// ── 冻结形状: confirmed_activity (真实智能体任务 / 链上活动行) ────────────────
+//
+// 公开网页要能列出「哪个任务 · 什么状态 · 哪个块 · 多少确认」, 而不是只有数字。这块就是那批行。
+// 形状**冻结** (字段名与取值域不许改), 内容一律**匿名短写**:
+//   · task = `sha256:` + sha256(域标签|taskKey) 的前 8 位十六进制 —— 绝不落 taskKey / taskId 原文
+//   · tx   = `sha256:` + sha256(域标签|txHash)  的前 8 位十六进制 —— 绝不落 txHash 原文
+//   · 不出现 DID / peerId / IP / 完整钱包地址 / 任务正文 —— `assertNoPrivateFields` 兜底
+// 数据源优先级: ① P5 链上索引 (真链上事实) → ② 索引不可用 → 退回脉冲事件, 并在快照里用
+//   `confirmed_activity_source` 如实标注 (chain-index / pulse-events / none)。
+// 确认数口径走 chain-config 门槛 (默认 confirmed=1 / finalized=12): 够不着门槛的行只报
+//   `observed`, **绝不冒充** confirmed/finalized。
+/** 冻结形状: 活动行上限 */
+exports.CONFIRMED_ACTIVITY_LIMIT = exports.PULSE_LIMITS.maxConfirmedActivity;
+/**
+ * 链上 escrow 事件名 → (kind, state) 的**唯一**映射表 (改这里才对, 别在别处写 switch)。
+ *
+ * kind 只能取冻结枚举的 5 个值, 链上有 6 类事件 → 按「任务生命周期 / 托管资金路径」归并:
+ *   · EscrowCreatedV2  委托创建 + 资金入托管              → task_created   / active
+ *   · ProofSubmittedV2 交付物验真摘要落链 (= 该笔交付完成) → task_completed / active (托管仍 ACTIVE, 等结算)
+ *   · ReleasedV2       结算出金                            → trade_settled  / released
+ *   · RefundedV2       托管退款                            → trade_settled  / refunded
+ *   · ExpiredV2        托管到期                            → trade_settled  / expired
+ *   · DisputedV2       资金冻结进入争议 (托管资金路径)      → trade_settled  / disputed
+ * 真信号在 `state` (kind 只是粗桶); 事件名不在表里 → 该条**不成行** (不猜)。
+ */
+exports.CHAIN_EVENT_ACTIVITY = {
+    EscrowCreatedV2: { kind: 'task_created', state: 'active' },
+    ProofSubmittedV2: { kind: 'task_completed', state: 'active' },
+    ReleasedV2: { kind: 'trade_settled', state: 'released' },
+    RefundedV2: { kind: 'trade_settled', state: 'refunded' },
+    ExpiredV2: { kind: 'trade_settled', state: 'expired' },
+    DisputedV2: { kind: 'trade_settled', state: 'disputed' },
+};
+/** 脉冲事件 → 冻结 kind 的映射 (索引不可用时的降级路径; 没有 taskProof 的事件不成行) */
+exports.PULSE_EVENT_ACTIVITY = {
+    task_posted: 'task_created',
+    task_accepted: 'task_accepted',
+    task_completed: 'task_completed',
+    trade_settled: 'trade_settled',
+    trade_verified: 'trade_verified',
+};
+/** 标识 → `sha256:<前 8 位十六进制>`。域标签隔离用途: 同一原值稳定 (可 join), 不同用途不串, 不可逆。 */
+function anonShortRef(value, domain = 'id') {
+    return `sha256:${nodeDigest(`${domain}|${String(value)}`).slice(0, 8)}`;
+}
+/** ISO8601 UTC 秒级 (`2026-09-22T05:31:00Z`) —— 冻结形状里 `at` 的格式。非法时间 → null */
+function isoSeconds(at) {
+    const n = Number(at);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    try {
+        return new Date(n).toISOString().replace(/\.\d{3}Z$/, 'Z');
+    }
+    catch {
+        return null;
+    }
+}
+/** 确认门槛归一化: 缺/非法 → chain-config 默认 (1/12); finalized 不许低于 confirmed */
+function normalizeActivityGates(g) {
+    const c = Number(g?.confirmed);
+    const f = Number(g?.finalized);
+    const confirmed = Number.isInteger(c) && c > 0 ? c : chain_config_js_1.DEFAULT_CONFIRMATIONS.confirmed;
+    const finalized = Number.isInteger(f) && f >= confirmed ? f : Math.max(confirmed, chain_config_js_1.DEFAULT_CONFIRMATIONS.finalized);
+    return { confirmed, finalized };
+}
+/**
+ * finality **只按确认数复算** (单一实现): 够 finalized → finalized; 够 confirmed → confirmed;
+ * 不够 / 非法 / 被回退过 → observed。行里原本自报的 finality 一律不复用 —— 不满足就是 observed。
+ */
+function finalityFromConfirmations(confirmations, gates, opts = {}) {
+    if (opts.suspect)
+        return 'observed';
+    const g = normalizeActivityGates(gates);
+    const c = Number(confirmations);
+    if (!Number.isFinite(c) || c < g.confirmed)
+        return 'observed';
+    return c >= g.finalized ? 'finalized' : 'confirmed';
+}
+function activityLimit(limit) {
+    const n = Math.floor(Number(limit));
+    if (!Number.isFinite(n))
+        return exports.CONFIRMED_ACTIVITY_LIMIT;
+    return Math.max(0, Math.min(exports.CONFIRMED_ACTIVITY_LIMIT, n));
+}
+/**
+ * 链上索引条目 → 冻结活动行 (**纯函数**, 不读盘不发 RPC, 便于单测)。
+ *   · suspect (被回退 / 链上已消失) 的记录**不成行** —— 它已经不在规范链上, 不该当活动列出
+ *   · 不认识的事件名 / 非法 taskKey·txHash / 缺观察时间 → 跳过 (不猜、不臆造)
+ *   · confirmations: 有 headBlock → head - block + 1 复算 (无 RPC, 用索引快照里的 head); 否则用记录值
+ *   · finality: 按 chain-config 门槛复算 (不够 → observed)
+ *   · 最新在前 (blockNumber desc, logIndex desc), 上限 25 行
+ */
+function buildConfirmedActivityFromIndex(entries, opts = {}) {
+    const gates = normalizeActivityGates(opts.gates);
+    const limit = activityLimit(opts.limit);
+    const chainId = Number.isInteger(Number(opts.chainId)) && Number(opts.chainId) >= 0 ? Number(opts.chainId) : 0;
+    const head = Number.isInteger(Number(opts.headBlock)) && Number(opts.headBlock) >= 0 ? Number(opts.headBlock) : null;
+    const out = [];
+    for (const e of Array.isArray(entries) ? entries : []) {
+        if (!e || e.suspect === true)
+            continue; // 回退过的记录不在规范链上 → 不成行
+        const map = exports.CHAIN_EVENT_ACTIVITY[String(e.eventName || '')];
+        if (!map)
+            continue; // 不认识的事件 → 跳过 (不猜)
+        const taskKey = String(e.taskKey || '').toLowerCase();
+        const txHash = String(e.txHash || '').toLowerCase();
+        if (!/^0x[0-9a-f]{64}$/.test(taskKey) || !/^0x[0-9a-f]{64}$/.test(txHash))
+            continue;
+        const block = Number(e.blockNumber);
+        const logIndex = Number(e.logIndex);
+        if (!Number.isInteger(block) || block < 0 || !Number.isInteger(logIndex) || logIndex < 0)
+            continue;
+        const atMs = Number(e.firstSeenAt);
+        const at = isoSeconds(atMs);
+        if (!at)
+            continue; // 没观察时间 → 不臆造时间, 不成行
+        const confirmations = head == null ? Math.max(0, Number(e.confirmations) || 0) : Math.max(0, head - block + 1);
+        out.push({
+            block, logIndex,
+            row: {
+                task: anonShortRef(taskKey, 'task'),
+                kind: map.kind,
+                state: map.state,
+                chain_id: chainId,
+                block,
+                tx: anonShortRef(txHash, 'tx'),
+                confirmations,
+                finality: finalityFromConfirmations(confirmations, gates),
+                at,
+            },
+        });
+    }
+    out.sort((a, b) => b.block - a.block || b.logIndex - a.logIndex);
+    return out.slice(0, limit).map((x) => x.row);
+}
+/**
+ * 脉冲事件 → 冻结活动行 (**纯函数**, 索引不可用时的降级路径)。
+ *   · 只有带 taskProof 的经济事件成行; state 一律 `unknown` —— 脉冲事件不带 escrow 结局, 不推
+ *   · 没有链上事实: chain_id / block / confirmations = 0, finality = observed (绝不冒充已确认)
+ *   · tx = 事件摘要短写 (不是交易哈希 —— 降级行没有 txHash, 字段名冻结只能这样填)
+ *   · 同一 (task, kind) 只留最新一条; 最新在前, 上限 25 行
+ */
+function buildConfirmedActivityFromEvents(events, opts = {}) {
+    const limit = activityLimit(opts.limit);
+    if (limit <= 0)
+        return [];
+    const all = [];
+    for (const e of Array.isArray(events) ? events : []) {
+        if (!isValidEvent(e))
+            continue;
+        const kind = exports.PULSE_EVENT_ACTIVITY[e.type];
+        if (!kind)
+            continue; // 非经济事件 (入网/能力/连接…) → 不成行
+        const proof = String(e.taskProof || '').toLowerCase();
+        if (!/^[0-9a-f]{16}$/.test(proof))
+            continue; // 没有任务摘要 → 不成行
+        const at = isoSeconds(e.occurredAt);
+        if (!at)
+            continue;
+        all.push({
+            at: e.occurredAt,
+            row: {
+                task: `sha256:${proof.slice(0, 8)}`,
+                kind,
+                state: 'unknown',
+                chain_id: 0,
+                block: 0,
+                tx: anonShortRef(`pulse|${e.sourceProof}|${e.occurredAt}|${e.type}`, 'tx'),
+                confirmations: 0,
+                finality: 'observed',
+                at,
+            },
+        });
+    }
+    all.sort((a, b) => b.at - a.at); // 最新在前
+    const seen = new Set();
+    const rows = [];
+    for (const x of all) {
+        const key = `${x.row.task}|${x.row.kind}`;
+        if (seen.has(key))
+            continue; // 同一任务同一动作只留最新一条
+        seen.add(key);
+        rows.push(x.row);
+        if (rows.length >= limit)
+            break;
+    }
+    return rows;
+}
+/** 纯函数降级: 直接从脉冲事件算活动行 (没有索引时用, source 如实写 pulse-events / none) */
+function confirmedActivityFromEvents(events, limit) {
+    const rows = buildConfirmedActivityFromEvents(events, { limit });
+    return { source: rows.length ? 'pulse-events' : 'none', rows, gates: normalizeActivityGates(chain_config_js_1.DEFAULT_CONFIRMATIONS) };
+}
+/** 惰性加载链上索引只读查询模块 (只读索引文件, 不发 RPC; 加载/读取失败 → 降级) */
+let chainQueryModule = null;
+async function readChainIndex(home) {
+    try {
+        if (!chainQueryModule)
+            chainQueryModule = (await Promise.resolve().then(() => __importStar(require('./chain/chain-index-query.js'))));
+        return chainQueryModule.readIndexFile({ home });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 解析活动行 (唯一入口): **先链上索引, 再脉冲降级**, 并如实报出来源。
+ * 索引文件不存在/读不出/没有任何可用行 → 退回脉冲事件; 两边都没有 → none (不编行)。
+ */
+async function resolveConfirmedActivity(q) {
+    const now = Number(q.now ?? Date.now());
+    const limit = activityLimit(q.limit);
+    const windowed = (Array.isArray(q.events) ? q.events : [])
+        .filter((e) => isValidEvent(e) && e.occurredAt >= now - exports.PULSE_LIMITS.windowMs);
+    // ① 链上索引优先 (真链上事实)
+    const reader = q.readIndex ?? readChainIndex;
+    try {
+        const file = await reader(q.home);
+        const entries = Array.isArray(file?.entries) ? file.entries : [];
+        if (entries.length > 0) {
+            const gates = normalizeActivityGates(file?.confirmations);
+            const rows = buildConfirmedActivityFromIndex(entries, {
+                gates,
+                headBlock: file?.headBlock,
+                chainId: file?.chainId,
+                limit,
+            });
+            if (rows.length > 0)
+                return { source: 'chain-index', rows, gates };
+        }
+    }
+    catch { /* 索引不可用 → 降级 (来源会在快照里标明) */ }
+    // ② 降级: 脉冲事件
+    return confirmedActivityFromEvents(windowed, limit);
+}
+// ── 同源计数 · 口径说明 · 链归属 (2026-09-22: 公开页数字不许自相矛盾) ──────────
+//
+// 起因: 真快照里 `totals.tasks=0` 而 `confirmed_activity` 有 25 行真实任务 —— 两块数据来自
+// **两套口径** (totals = 24h 脉冲事件窗口; confirmed_activity = 链上索引全量), 但页面上它们同屏,
+// 读者只会读成"自相矛盾/在撒谎"。修法不是把数字改漂亮, 而是:
+//   ① `activity_totals` = 与 confirmed_activity **同源**的计数 (rows 恒等于该数组长度);
+//   ② `totals_scope`   = totals 的口径说明 + `differs_from_activity` 标记;
+//   ③ `chain_id_scope` = 上表各行属于哪条链 (本机 31337 ≠ 真网 Base Sepolia 84532);
+//   ④ `snapshotConsistencyIssues` = 导出前的自检 (两个数字打架就拒绝导出)。
+/** 公网测试网 (Base Sepolia) chainId —— 只做**归属说明**, 不代表快照观察到了公网事件 */
+exports.PUBLIC_TESTNET_CHAIN_ID = 84532;
+/** 公网主网 (Base) chainId —— 同上, 只做归属说明 */
+exports.PUBLIC_MAINNET_CHAIN_ID = 8453;
+/**
+ * chainId → 展示用网络名 (只回答"这一屏的行属于哪条链")。
+ * 认不出的 chain id **不编名字** (chainLabelOf → null), 也不许算成公网。
+ */
+exports.CHAIN_LABELS = {
+    [chain_config_js_1.LOCAL_DEV_CHAIN_ID]: { zh: '本机隔离开发链', en: 'local isolated dev chain', publicNetwork: false },
+    [exports.PUBLIC_TESTNET_CHAIN_ID]: { zh: 'Base Sepolia 测试网', en: 'Base Sepolia testnet', publicNetwork: true },
+    [exports.PUBLIC_MAINNET_CHAIN_ID]: { zh: 'Base 主网', en: 'Base mainnet', publicNetwork: true },
+};
+/** chainId 的展示名; 认不出的 chain id → null (不编名字) */
+function chainLabelOf(chainId) {
+    const id = Number(chainId);
+    return Number.isInteger(id) ? exports.CHAIN_LABELS[id] ?? null : null;
+}
+/** 是不是公网链 id (白名单; 认不出的一律**不算**公网 —— 不替读者认领归属) */
+function isPublicChainId(chainId) {
+    return chainLabelOf(chainId)?.publicNetwork === true;
+}
+/**
+ * 活动行 → 同源计数 (**纯函数**; 输入就是 `confirmed_activity` 本身)。
+ * 存在的唯一理由: 公开页同时显示 totals 与本表行数, 两个数字肉眼可能"打架" ——
+ * 那就让它们同源可核: `activity_totals.rows` 恒等于 `confirmed_activity.length`。
+ */
+function summarizeActivityRows(rows, opts) {
+    const list = (Array.isArray(rows) ? rows : []).filter((r) => !!r);
+    const tasks = new Set();
+    const completed = new Set();
+    const settled = new Set();
+    const by_finality = { observed: 0, confirmed: 0, finalized: 0 };
+    for (const r of list) {
+        const t = String(r.task || '');
+        if (t)
+            tasks.add(t);
+        if (t && r.kind === 'task_completed')
+            completed.add(t);
+        if (t && r.kind === 'trade_settled')
+            settled.add(t);
+        if (r.finality === 'observed' || r.finality === 'confirmed' || r.finality === 'finalized') {
+            by_finality[r.finality] += 1;
+        }
+    }
+    return {
+        source: opts.source,
+        rows: list.length,
+        tasks: tasks.size,
+        tasks_completed: completed.size,
+        tasks_settled: settled.size,
+        by_finality,
+        gates: normalizeActivityGates(opts.gates),
+    };
+}
+/** 活动行 → 链归属 (**纯函数**)。所有结论都从行本身推, 不引用外部状态 → 不可能与行数打架。 */
+function buildChainIdScope(rows) {
+    const list = (Array.isArray(rows) ? rows : []).filter((r) => !!r);
+    const counts = new Map();
+    for (const r of list) {
+        const id = Number(r.chain_id);
+        if (!Number.isInteger(id) || id < 0)
+            continue;
+        counts.set(id, (counts.get(id) || 0) + 1);
+    }
+    const chain_ids = Array.from(counts.keys()).sort((a, b) => a - b);
+    let primary = 0;
+    let best = 0;
+    for (const id of chain_ids) { // 升序遍历 + 严格大于 → 并列取小
+        const c = counts.get(id);
+        if (c > best) {
+            best = c;
+            primary = id;
+        }
+    }
+    const label = chain_ids.length ? chainLabelOf(primary) : null;
+    const publicIds = chain_ids.filter(isPublicChainId);
+    const publicRows = publicIds.reduce((n, id) => n + (counts.get(id) || 0), 0);
+    const pub = exports.CHAIN_LABELS[exports.PUBLIC_TESTNET_CHAIN_ID];
+    // 点名口径: 提示里写出的公网链必须是**行里真出现过的**; 一条都没有才退回对照链
+    // (否则会出现「上表 3 行来自 chainId 8453(Base 主网)」却说「公网链(Base Sepolia 84532) 3 行」的自相矛盾)
+    const pubZh = publicIds.length
+        ? publicIds.map((id) => `${exports.CHAIN_LABELS[id].zh} ${id}`).join('、')
+        : `${pub.zh} ${exports.PUBLIC_TESTNET_CHAIN_ID}`;
+    const pubEn = publicIds.length
+        ? publicIds.map((id) => `${exports.CHAIN_LABELS[id].en} ${id}`).join(', ')
+        : `${pub.en} ${exports.PUBLIC_TESTNET_CHAIN_ID}`;
+    const rows_ = list.length;
+    const multi = chain_ids.length > 1 ? `（上表共 ${chain_ids.length} 条链）` : '';
+    const note = rows_ === 0
+        ? {
+            zh: 'chain_id 归属: 本快照没有链上活动行 —— 不是"链上没事件", 而是这一轮没有可列出的行',
+            en: 'chain_id scope: no on-chain activity row in this snapshot — not "nothing happened on chain", just no listable row this round',
+        }
+        : {
+            zh: `chain_id 归属: 上表 ${rows_} 行来自 chainId ${primary}${label ? `（${label.zh}）` : ''}${multi} · ` +
+                `公网链（${pubZh}）${publicRows} 行` +
+                `${publicRows === 0 ? ' —— 这不是公网活动' : ''}`,
+            en: `chain_id scope: all ${rows_} rows above come from chainId ${primary}${label ? ` (${label.en})` : ''}${chain_ids.length > 1 ? ` (${chain_ids.length} chains in total)` : ''} · ` +
+                `public network (${pubEn}) rows: ${publicRows}` +
+                `${publicRows === 0 ? ' — this is not public-network activity' : ''}`,
+        };
+    return {
+        chain_ids,
+        activity_chain_id: primary,
+        activity_chain_label: label ? { zh: label.zh, en: label.en } : null,
+        is_public_network: chain_ids.length > 0 ? isPublicChainId(primary) : false,
+        public_network_rows: publicRows,
+        public_network: { chain_id: exports.PUBLIC_TESTNET_CHAIN_ID, label: { zh: pub.zh, en: pub.en } },
+        note,
+    };
+}
+/**
+ * 快照自检: 公开页会**同屏展示**的数字之间不许自相矛盾。返回问题清单 (空 = 通过)。
+ *   ① `activity_totals` 必须在 (与行同源的计数不能缺)
+ *   ② `activity_totals.rows` === `confirmed_activity.length`
+ *   ③ `by_finality` 三档之和 === 行数 (没有第四条腿)
+ *   ④ `activity_totals.source` === `confirmed_activity_source` (两块来源标注必须一致)
+ *   ⑤ 行里有任务 而 `totals.tasks === 0` 时, 必须有口径说明 note
+ *      (页面不许出现「0 个任务」与「N 行任务」并存而**不解释**)
+ */
+function snapshotConsistencyIssues(snap) {
+    const issues = [];
+    const rows = Array.isArray(snap?.confirmed_activity) ? snap.confirmed_activity : [];
+    const at = snap?.activity_totals;
+    if (!at || typeof at !== 'object') {
+        return ['activity_totals 缺失 (与 confirmed_activity 同源的计数必须一起给)'];
+    }
+    if (Number(at.rows) !== rows.length)
+        issues.push(`activity_totals.rows=${at.rows} ≠ confirmed_activity.length=${rows.length}`);
+    const bf = at.by_finality || {};
+    const sum = ['observed', 'confirmed', 'finalized'].reduce((n, k) => n + (Number(bf[k]) || 0), 0);
+    if (sum !== rows.length)
+        issues.push(`by_finality 三档之和=${sum} ≠ 行数=${rows.length}`);
+    if (String(at.source || '') !== String(snap?.confirmed_activity_source || '')) {
+        issues.push(`activity_totals.source=${at.source} ≠ confirmed_activity_source=${snap?.confirmed_activity_source}`);
+    }
+    const tasks = Number(at.tasks) || 0;
+    const pulseTasks = Number(snap?.totals?.tasks) || 0;
+    if (rows.length > 0 && tasks > 0 && pulseTasks === 0) {
+        const notes = Array.isArray(snap.notes) ? snap.notes.join(' ') : '';
+        const explained = notes.includes('脉冲事件') && notes.includes(String(rows.length)) &&
+            (notes.includes('链上索引') || notes.includes('chain-index'));
+        if (!explained)
+            issues.push(`totals.tasks=0 与 ${rows.length} 行任务并存, 却没有口径说明 note`);
+    }
+    return issues;
+}
 function computeSnapshot(events, opts) {
     const now = opts.now;
     const fresh_until = now + exports.PULSE_LIMITS.snapshotTtlMs;
     if (opts.unavailable) {
+        const emptyRows = [];
+        const gates = normalizeActivityGates(chain_config_js_1.DEFAULT_CONFIRMATIONS);
         return {
             status: 'unavailable',
             generated_at: now,
@@ -301,8 +716,20 @@ function computeSnapshot(events, opts) {
             scope: 'observed',
             scope_label: { zh: '当前节点观察到', en: 'Observed by this node' },
             totals: { nodes: 0, agents: 0, active_agents: 0, seen_last_24h: 0, tasks: 0, tasks_completed: 0, tasks_verified: 0, signatures: 0 },
+            totals_scope: {
+                source: 'pulse-events', window_ms: exports.PULSE_LIMITS.windowMs,
+                label: {
+                    zh: `只统计本节点 ${exports.PULSE_LIMITS.windowMs / 3600000}h 观察窗口内收到的脉冲事件 (本节点自己上报的)`,
+                    en: `Only pulse events received by this node within the ${exports.PULSE_LIMITS.windowMs / 3600000}h observation window (reported by this node itself)`,
+                },
+                differs_from_activity: false,
+            },
             capabilities: [],
             recent_activity: [],
+            confirmed_activity: emptyRows,
+            confirmed_activity_source: 'none',
+            activity_totals: summarizeActivityRows(emptyRows, { source: 'none', gates }),
+            chain_id_scope: buildChainIdScope(emptyRows),
             notes: ['观察层暂不可用 — 这不是"网络为空"'],
         };
     }
@@ -365,6 +792,39 @@ function computeSnapshot(events, opts) {
         notes.push('单节点观察: 这是本节点能看到的部分网络, 不是全网精确总量');
     else
         notes.push(`多签名来源汇总 (${signedNodes} 个签名节点)`);
+    // 活动行来源如实标注 (chain-index = 真链上事实; pulse-events = 降级, 非链上确认)
+    const activity = opts.confirmedActivity ?? confirmedActivityFromEvents(window);
+    // 同源计数 + 链归属: **输入就是上表那批行**, 所以不可能与行数/链 id 打架
+    const activity_totals = summarizeActivityRows(activity.rows, { source: activity.source, gates: activity.gates });
+    const chain_id_scope = buildChainIdScope(activity.rows);
+    const totals_scope = {
+        source: 'pulse-events',
+        window_ms: exports.PULSE_LIMITS.windowMs,
+        label: {
+            zh: `只统计本节点 ${exports.PULSE_LIMITS.windowMs / 3600000}h 观察窗口内收到的脉冲事件 (本节点自己上报的)`,
+            en: `Only pulse events received by this node within the ${exports.PULSE_LIMITS.windowMs / 3600000}h observation window (reported by this node itself)`,
+        },
+        differs_from_activity: activity_totals.rows > 0 &&
+            (tasks.size !== activity_totals.tasks || tasksCompleted.size !== activity_totals.tasks_completed),
+    };
+    if (activity.source === 'chain-index') {
+        notes.push(`confirmed_activity 来自链上索引 (chain-index): ${activity_totals.rows} 行 · ${activity_totals.tasks} 个不同任务 · ` +
+            `finality 分布 observed=${activity_totals.by_finality.observed} / confirmed=${activity_totals.by_finality.confirmed} / ` +
+            `finalized=${activity_totals.by_finality.finalized} (三档之和 = 行数); 最新在前, 上限 ${exports.CONFIRMED_ACTIVITY_LIMIT} 行; ` +
+            `确认门槛 confirmed=${activity.gates.confirmed} · finalized=${activity.gates.finalized}`);
+    }
+    else if (activity.source === 'pulse-events') {
+        notes.push('confirmed_activity 降级为脉冲事件 (pulse-events): 非链上确认 —— chain_id/block/confirmations=0 且 finality=observed');
+    }
+    // 两套计数口径不同时**必须**解释 —— 页面不许出现「0 个任务」与「N 行任务」并存而不解释
+    if (totals_scope.differs_from_activity) {
+        notes.push(`口径不同, 不是数据丢失: totals.tasks/tasks_completed/tasks_verified/signatures 只数本节点 ` +
+            `${exports.PULSE_LIMITS.windowMs / 3600000}h 窗口内的脉冲事件 (本快照 tasks=${tasks.size} · tasks_completed=${tasksCompleted.size} · ` +
+            `tasks_verified=${tasksVerified.size} · signatures=${signatureKeys.size}); 上表 ${activity_totals.rows} 行来自链上索引 ` +
+            `(全量, 不是 ${exports.PULSE_LIMITS.windowMs / 3600000}h 窗口) —— 同源计数见 activity_totals`);
+    }
+    if (activity_totals.rows > 0)
+        notes.push(chain_id_scope.note.zh);
     return {
         status: 'live',
         generated_at: now,
@@ -383,8 +843,13 @@ function computeSnapshot(events, opts) {
             tasks_verified: tasksVerified.size,
             signatures: signatureKeys.size, // 真实签名次数 (只计数)
         },
+        totals_scope,
         capabilities,
         recent_activity: recent,
+        confirmed_activity: activity.rows,
+        confirmed_activity_source: activity.source,
+        activity_totals,
+        chain_id_scope,
         notes,
     };
 }
@@ -396,7 +861,15 @@ async function getNetworkPulse(opts = {}) {
     if (!opts.force) {
         try {
             const cached = JSON.parse(fs.readFileSync(snapshotFile(opts.home), 'utf-8'));
-            if (cached && Number.isFinite(cached.generated_at) && cached.generated_at + exports.PULSE_LIMITS.snapshotTtlMs > now)
+            // 老版本写的缓存缺冻结字段 `confirmed_activity` (或后来的 totals_scope / activity_totals /
+            // chain_id_scope) → 视为**过期形状**, 重算 (不能把缺字段的快照发出去 ——
+            // 缺 activity_totals 就会在页面上重新变成"两个数字打架"
+            const shapeOk = Array.isArray(cached?.confirmed_activity)
+                && typeof cached?.confirmed_activity_source === 'string'
+                && !!cached?.totals_scope
+                && !!cached?.activity_totals
+                && !!cached?.chain_id_scope;
+            if (shapeOk && cached && Number.isFinite(cached.generated_at) && cached.generated_at + exports.PULSE_LIMITS.snapshotTtlMs > now)
                 return cached;
         }
         catch { /* 无缓存 */ }
@@ -408,7 +881,9 @@ async function getNetworkPulse(opts = {}) {
     catch (e) {
         return computeSnapshot([], { now, unavailable: true });
     }
-    const snap = computeSnapshot(events, { now });
+    // 活动行优先取 P5 链上索引 (真链上事实); 索引不可用 → 退回脉冲事件, 并在快照里标出来源
+    const confirmedActivity = await resolveConfirmedActivity({ home: opts.home, events, now });
+    const snap = computeSnapshot(events, { now, confirmedActivity });
     try {
         fs.mkdirSync((0, exports.pulseDir)(opts.home), { recursive: true });
         fs.writeFileSync(snapshotFile(opts.home), JSON.stringify(snap), 'utf8');