@bolloon/bolloon-agent 0.4.26 → 0.4.28

package/dist/agents/trace-export.js

@@ -0,0 +1,125 @@
+/**
+ * trace-export.ts — 智能体**工具执行轨迹**的导出/解析 (2026-09-18)
+ *
+ * 定位: Run 的 steps[] 就是这台机器上真实发生过的工具调用事实
+ *   (n / ts / tool / argsDigest / ok / ms / summary / error)。
+ * 这一层只做一件事: 把这份事实变成**可读、可交换、可再解析**的文本/JSON,
+ * 好让 App、CLI、Web 与外部工具(如小红书小工具)看到同一份轨迹。
+ *
+ * 文本格式 (小工具侧解析器依赖, 改前先看 minitools/agent-card/src/assets/app.js 的 parseTraceText):
+ *   # Bolloon 执行轨迹 · run <runId> (<N> 步)
+ *   1. [ok] 2026-09-18T08:46:15.093Z shell_exec — ls -la /tmp (12ms)
+ *   2. [fail] 2026-09-18T08:46:17.001Z write_file — EACCES: permission denied (3ms)
+ *   规则: "<n>. [ok|fail] <无空格时间戳> <工具名> — <细节>" —— 时间戳与工具名不能含空格。
+ */
+export const TRACE_HEADER_PREFIX = '# Bolloon 执行轨迹';
+function stepDetail(s) {
+    const base = String(s.summary || s.error || (s.ok ? '完成' : '失败')).replace(/\s+/g, ' ').trim();
+    const ms = s.ms ? ` (${s.ms}ms)` : '';
+    const args = s.argsDigest ? ` [args:${String(s.argsDigest).slice(0, 8)}]` : '';
+    return `${base}${args}${ms}`.slice(0, 400);
+}
+/** Run → 轨迹 JSON (机器可读; 所有消费方都应基于这个结构, 而不是各自解析文本) */
+export function runToTraceJson(run) {
+    const steps = (run.steps || []).map((s) => ({
+        n: s.n,
+        ts: s.ts,
+        tool: s.tool,
+        ok: !!s.ok,
+        ms: s.ms,
+        summary: s.summary,
+        error: s.error,
+        argsDigest: s.argsDigest,
+    }));
+    const ok = steps.filter((s) => s.ok).length;
+    const byTool = new Map();
+    for (const s of steps) {
+        const cur = byTool.get(s.tool) || { tool: s.tool, count: 0, fail: 0 };
+        cur.count += 1;
+        if (!s.ok)
+            cur.fail += 1;
+        byTool.set(s.tool, cur);
+    }
+    return {
+        schema: 'bolloon-agent-trace/1',
+        runId: run.runId,
+        goalId: run.goalId,
+        surface: run.surface,
+        status: run.status,
+        goal: run.goal,
+        startedAt: run.startedAt || (run.steps || [])[0]?.ts,
+        updatedAt: run.updatedAt,
+        steps,
+        counts: { total: steps.length, ok, fail: steps.length - ok, totalMs: steps.reduce((a, s) => a + (s.ms || 0), 0) },
+        tools: Array.from(byTool.values()).sort((a, b) => b.count - a.count),
+        evidence: run.evidence,
+        error: run.error,
+    };
+}
+/** Run → 轨迹文本 (人可读 + 可被小工具解析; 供 CLI / 复制粘贴) */
+export function runToTraceText(run, opts = {}) {
+    const steps = (run.steps || []).slice(opts.limit ? Math.max(0, (run.steps || []).length - opts.limit) : 0);
+    const lines = [];
+    lines.push(`${TRACE_HEADER_PREFIX} · run ${run.runId} (${(run.steps || []).length} 步)`);
+    if (run.goal)
+        lines.push(`# 目标: ${String(run.goal).replace(/\s+/g, ' ').slice(0, 160)}`);
+    lines.push(`# 状态: ${run.status}${run.goalId ? ` · goal ${run.goalId}` : ''}${run.surface ? ` · surface ${run.surface}` : ''}`);
+    if (!steps.length)
+        lines.push('# (这次运行没有工具步骤)');
+    for (const s of steps) {
+        lines.push(`${s.n}. [${s.ok ? 'ok' : 'fail'}] ${s.ts} ${s.tool} — ${stepDetail(s)}`);
+    }
+    if (run.error)
+        lines.push(`# 结束原因: ${String(run.error).replace(/\s+/g, ' ').slice(0, 200)}`);
+    return lines.join('\n');
+}
+/**
+ * 解析轨迹文本 (容错: 只认 "<n>. [ok|fail] <ts> <tool> — <detail>" 这一行格式)。
+ * 用于: 把别处(小工具/别的机器)的轨迹读回来, 以及本模块的自校验往返。
+ */
+export function parseTraceText(text) {
+    const out = { steps: [] };
+    const lines = String(text || '').split('\n');
+    const re = /^\s*(\d+)\.\s*\[(ok|fail)\]\s*(\S+)\s+(\S+)\s*(?:—\s*)?([\s\S]*)$/;
+    for (const raw of lines) {
+        const line = raw.replace(/\r$/, '');
+        if (line.startsWith(TRACE_HEADER_PREFIX)) {
+            out.header = line;
+            continue;
+        }
+        if (line.startsWith('# 目标:')) {
+            out.goal = line.slice(5).trim();
+            continue;
+        }
+        if (line.startsWith('# 状态:')) {
+            out.status = line.slice(5).trim();
+            continue;
+        }
+        if (line.startsWith('# 结束原因:')) {
+            out.errorLine = line.slice(7).trim();
+            continue;
+        }
+        if (!line.trim() || line.startsWith('#'))
+            continue;
+        const m = re.exec(line);
+        if (!m)
+            continue;
+        const detail = String(m[5] || '');
+        const msMatch = /\s*\((\d+)ms\)\s*$/.exec(detail);
+        out.steps.push({
+            n: Number(m[1]),
+            ok: m[2] === 'ok',
+            ts: m[3],
+            tool: m[4],
+            ms: msMatch ? Number(msMatch[1]) : undefined,
+            summary: msMatch ? detail.slice(0, msMatch.index).trim() : detail.trim(),
+        });
+    }
+    return out;
+}
+/** 一行摘要 (CLI 列表/日志用) */
+export function summarizeTrace(run) {
+    const j = runToTraceJson(run);
+    const tools = j.tools.slice(0, 3).map((t) => `${t.tool}×${t.count}`).join(' ');
+    return `${j.counts.total} 步 (✓${j.counts.ok}/✗${j.counts.fail}, ${j.counts.totalMs}ms)${tools ? ` · ${tools}` : ''}`;
+}

package/dist/agents/write-staging.js

@@ -18,9 +18,16 @@ const home = () => process.env.HOME || os.homedir() || '/tmp';
 export function writeLogDir(homeDir = home()) {
     return path.join(homeDir, '.bolloon', 'write-log');
 }
-/** 生成唯一 stage id */
+/**
+ * 生成唯一 stage id。
+ * ★ 2026-09-18: 加**进程内单调序号** —— 原来只有 `Date.now()-随机`, 同一毫秒内的两次写入
+ * 顺序由随机后缀决定, `listStagedWrites` 的"最新在前"就不成立了 (真跑: 同毫秒 a.txt/b.txt 偶发反序,
+ * 让 write-staging 单测在全量跑时随机变红)。序号按 3 位 36 进制, 与时间戳一起保证字典序 == 发生顺序。
+ */
+let stageSeq = 0;
 function genId() {
-    return `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const seq = (stageSeq++ % 46656).toString(36).padStart(3, '0');
+    return `${Date.now()}-${seq}-${Math.random().toString(36).substring(2, 8)}`;
 }
 /**
  * 写前暂存: 记录一次写操作 (准备阶段). 返回记录; 失败静默返回 null.
@@ -54,13 +61,14 @@ export async function listStagedWrites(homeDir = home()) {
         return [];
     }
     const out = [];
-    for (const f of files.filter(f => f.endsWith('.json')).sort().reverse()) {
+    for (const f of files.filter(f => f.endsWith('.json'))) {
         try {
             out.push(JSON.parse(await fs.readFile(path.join(dir, f), 'utf-8')));
         }
         catch { /* 坏文件跳过 */ }
     }
-    return out;
+    // 最新在前: 先按 createdAt, 同一毫秒再按 id (id 内含单调序号) —— 确定性, 不看 readdir 顺序
+    return out.sort((a, b) => (b.createdAt - a.createdAt) || String(b.id).localeCompare(String(a.id)));
 }
 /** 撤销最近一次写 (若文件内容仍等于 afterContent → 恢复 beforeContent). 返回是否撤销. */
 export async function undoLastWrite(homeDir = home()) {

package/dist/agents/x402/goal-run-bridge.js

@@ -0,0 +1,109 @@
+/**
+ * goal-run-bridge.ts — 交易证据接入 Run / Goal (Phase 3, 2026-09-16)
+ *
+ * 支付不能只是工具副作用: 一次 Run 必须能回答 —— 为什么付款、买了什么、花了多少、
+ * 是否真结算、拿到什么、资源是否验证通过、结果对 Goal 有没有帮助。
+ *
+ * 事件映射 (与 leo 的规格一致):
+ *   discovered → transaction.discovered · quoted → transaction.quoted · policy_denied → transaction.policy_denied
+ *   paying → transaction.paying · settled → transaction.settled · delivered → transaction.delivered
+ *   verified → transaction.verified · delivery_failed/verification_failed → 同名
+ *
+ * Goal 侧只在 **交易 verified + 资源执行成功 + 命中判据** 时累计成功证据;
+ * 仅付款成功或仅拿到内容 **不能**满足 Goal 判据。
+ */
+import { recordStep, addRunEvidence } from '../run-store.js';
+import { addEvidence as addGoalEvidenceViaStore } from '../goal-store.js';
+import { aggregateMilestones, milestoneGoalEligibility } from './milestone-settlement.js';
+export function bridgeEventFor(status) {
+    switch (status) {
+        case 'discovered': return 'transaction.discovered';
+        case 'quoted': return 'transaction.quoted';
+        case 'policy_denied': return 'transaction.policy_denied';
+        case 'paying':
+        case 'payment_required': return 'transaction.paying';
+        case 'settled': return 'transaction.settled';
+        case 'delivered': return 'transaction.delivered';
+        case 'verified': return 'transaction.verified';
+        case 'delivery_failed': return 'transaction.delivery_failed';
+        case 'verification_failed': return 'transaction.verification_failed';
+        default: return 'transaction.quoted';
+    }
+}
+/** 一次交易的证据行 (写进 Run evidence / Goal evidence 的同一组字段) */
+export function transactionEvidenceLines(rec) {
+    // 2026-09-18: `goal-store.addEvidence` 每行**截断 300 字** —— 所以审计关键字段必须排在**前面**,
+    //   哈希类(长且可从交易记录反查)放后面。真跑抓到过: verificationTrust/executionOk 被截掉。
+    return [
+        `transactionId=${rec.transactionId}`,
+        `itemId=${rec.itemId}`,
+        `transactionStatus=${rec.status}`,
+        `paymentMode=${rec.paymentMode}`,
+        `chainSettled=${rec.chainSettled}`,
+        `settlementFact=${rec.settlementFact || '(legacy-未记)'}`, // 两层状态: 钱到底动没动, 审计一眼可见
+        `verificationTrust=${rec.verificationTrust || 'unverified'}`,
+        `protocolVerified=${rec.protocolVerified === true}`,
+        ...(rec.execution ? [`executionOk=${rec.execution.ok === true} schemaOk=${rec.execution.schemaOk === true}`] : []),
+        ...(rec.resourceOutcome ? [`resourceInstalled=${rec.resourceOutcome.installed} resourceExecuted=${rec.resourceOutcome.executed} outputContract=${rec.resourceOutcome.outputContract} criteriaHit=${rec.resourceOutcome.criteriaHit}${rec.resourceOutcome.failureStage ? ` failureStage=${rec.resourceOutcome.failureStage}` : ''}`] : []),
+        ...(rec.responsibility ? [`responsibility=${rec.responsibility.type}(${rec.responsibility.reason})`] : []),
+        ...(rec.milestones?.length ? (() => { const a = aggregateMilestones(rec.milestones); return [`milestones=${a.verified}/${a.total}`, `milestoneSettlement=${a.settlementFact}`]; })() : []),
+        ...(rec.dispute ? [`dispute=opened(${rec.dispute.reason})`, `disputeResolved=${rec.dispute.resolution ? rec.dispute.resolution.decision : 'no'}`] : []),
+        // 长哈希垫底 (可从交易记录反查; 300 字截断时优先牺牲它们, 而不是上面的判定字段)
+        `txHash=${rec.txHash || '(none)'}`,
+        `receiptHash=${rec.receiptHash || '(none)'}`,
+        `contentHash=${rec.contentHash || '(none)'}`,
+    ];
+}
+/**
+ * 把一笔交易写进 Run (step + evidence) 与 Goal (仅在满足条件时)。
+ * @param opts.goalCriteriaHit 资源执行结果是否命中 Goal 判据 (由调用方判定, 默认 false)
+ * @param opts.executionOk 资源是否被实际执行且符合契约
+ */
+export async function bridgeTransactionToRunGoal(rec, opts = {}) {
+    const out = { runId: opts.runId, goalId: opts.goalId, stepWritten: false, evidenceWritten: false, goalEvidenceWritten: false };
+    const lines = transactionEvidenceLines(rec);
+    const ok = rec.status === 'verified' || rec.status === 'delivered';
+    if (opts.runId) {
+        try {
+            const step = {
+                tool: 'x402_transaction',
+                ok,
+                summary: `${bridgeEventFor(rec.status)} · ${opts.summary || rec.itemId} (${rec.amount || rec.price || '?'} ${rec.currency || ''} via ${rec.paymentMode} · 结算 ${rec.settlementFact || '?'})`,
+                error: ok ? undefined : (rec.failureReason || rec.status),
+                args: { itemId: rec.itemId, amount: rec.amount, currency: rec.currency, network: rec.network, requestId: rec.requestId },
+            };
+            await recordStep(opts.runId, step);
+            out.stepWritten = true;
+            await addRunEvidence(opts.runId, lines);
+            out.evidenceWritten = true;
+        }
+        catch { /* 记账失败不改变交易事实, 但上面会让 out.* 保持 false (调用方可见) */ }
+    }
+    // Goal 侧: 只有 verified + 执行成功 + 命中判据 才计入成功证据
+    if (opts.goalId) {
+        // 纵深防御 + Phase 4 门槛: 链上结算 + 全部里程碑完成 + 无争议 + 执行成功 + 命中判据
+        // (partially_settled 一律不算 —— leo: 不要让 partially_settled 直接进 Goal 成功证据)
+        const elig = milestoneGoalEligibility(rec, { executionOk: opts.executionOk, goalCriteriaHit: opts.goalCriteriaHit });
+        const eligible = elig.eligible;
+        try {
+            if (eligible) {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `付费资源已执行并命中判据: ${lines.join(' ')}`,
+                ]);
+                out.goalEvidenceWritten = true;
+            }
+            else if (rec.status === 'verified' || (rec.milestones?.length || 0) > 0) {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `付费资源未达成功证据门槛 (${elig.reason}): ${lines.join(' ')}`,
+                ]);
+            }
+            else {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `交易未成立 (${rec.status}): ${lines.join(' ')}`,
+                ]);
+            }
+        }
+        catch { /* 同上 */ }
+    }
+    return out;
+}

package/dist/agents/x402/milestone-settlement.js

@@ -0,0 +1,150 @@
+/**
+ * milestone-settlement.ts — 里程碑结算 / 争议 / 责任落地 (Phase 4, 2026-09-18)
+ *
+ * leo 的 Phase 4:
+ *   4.1 **PartiallySettled**: 分阶段服务按里程碑结算 (第一版只支持明确里程碑)
+ *       每里程碑: milestoneId / amount / paymentStatus / deliveryStatus / verificationStatus / evidence
+ *       规则: 部分成功 → partially_settled; 全部支付且全部交付验证 → verified; 任一交付失败 → disputed 或 delivery_failed
+ *       ★ `partially_settled` **不许**直接进 Goal 成功证据
+ *   4.2 **争议**: disputed / refund_pending / refunded; 争议必须绑定
+ *       原始报价 · Payment Header · facilitator response · txHash · 内容哈希 · 签名信封 · Run step · Goal evidence · 失败时点 · 责任候选
+ *       三条禁令: 不能自动重付 · 不能标 verified · **不能静默关闭**
+ *   4.3 **责任判定**: 机器只给候选 (Phase 0 的 deriveResponsibility), 候选连同证据进交易记录 + Run/Goal 证据
+ */
+import { deriveResponsibility } from './settlement-state.js';
+/** 里程碑的不变式: 金额必须是正整数原子单位字符串 (不许浮点/负数/空) */
+export function validateMilestoneSpec(m) {
+    if (!m.milestoneId)
+        return { ok: false, reason: 'milestoneId 不能为空' };
+    if (!/^\d+$/.test(String(m.amount)))
+        return { ok: false, reason: `amount 必须是正整数原子单位字符串, 实际: ${m.amount}` };
+    if (Number(m.amount) <= 0)
+        return { ok: false, reason: 'amount 必须大于 0' };
+    return { ok: true };
+}
+export function makeMilestone(m) {
+    const chk = validateMilestoneSpec(m);
+    if (!chk.ok)
+        throw new Error(chk.reason);
+    return {
+        milestoneId: m.milestoneId, title: m.title, amount: String(m.amount),
+        paymentStatus: 'unpaid', deliveryStatus: 'pending', verificationStatus: 'pending',
+        evidence: [], updatedAt: new Date().toISOString(),
+    };
+}
+/** 里程碑总金额必须等于交易金额 (否则就是账不平) */
+export function milestonesMatchAmount(ms, amount) {
+    const sum = ms.reduce((a, m) => a + BigInt(m.amount || '0'), 0n).toString();
+    if (amount && String(amount) !== sum)
+        return { ok: false, sum, reason: `里程碑金额合计 ${sum} ≠ 交易金额 ${amount}` };
+    return { ok: true, sum };
+}
+export function aggregateMilestones(ms) {
+    const list = ms || [];
+    const paid = list.filter((m) => m.paymentStatus === 'paid').length;
+    const delivered = list.filter((m) => m.deliveryStatus === 'delivered').length;
+    const verified = list.filter((m) => m.verificationStatus === 'verified').length;
+    const failed = list.filter((m) => m.deliveryStatus === 'failed' || m.verificationStatus === 'failed').length;
+    const allComplete = list.length > 0 && verified === list.length;
+    const anyProgress = paid > 0 || delivered > 0 || verified > 0;
+    const partiallyComplete = anyProgress && !allComplete && failed === 0;
+    const next = list.find((m) => m.verificationStatus !== 'verified' && m.deliveryStatus !== 'failed');
+    let settlementFact = 'unpaid';
+    if (allComplete)
+        settlementFact = 'fully_settled';
+    else if (partiallyComplete)
+        settlementFact = 'partially_settled';
+    else if (paid > 0 || delivered > 0)
+        settlementFact = 'payment_submitted';
+    const shouldDispute = failed > 0;
+    const reason = shouldDispute
+        ? `${failed} 个里程碑交付/验真失败 → 进争议 (不许静默关闭)`
+        : allComplete ? '全部里程碑支付+交付+验真完成'
+            : partiallyComplete ? `${verified}/${list.length} 个里程碑完成 → partially_settled (不算完成, 也不进 Goal 成功证据)`
+                : list.length === 0 ? '没有里程碑 (单笔交易)' : '还没有里程碑完成';
+    return { total: list.length, paid, delivered, verified, failed, allComplete, partiallyComplete, nextMilestoneId: next?.milestoneId, settlementFact, shouldDispute, reason };
+}
+/** 应用一个里程碑结果并给出应落的结算事实 (纯函数; 落盘由调用方做, 保证可测) */
+export function applyMilestoneResult(ms, milestoneId, result) {
+    const list = (ms || []).map((m) => ({ ...m, evidence: [...(m.evidence || [])] }));
+    const target = list.find((m) => m.milestoneId === milestoneId);
+    if (!target)
+        return { milestones: list, aggregate: aggregateMilestones(list), ok: false, reason: `没有这个里程碑: ${milestoneId}` };
+    if (result.paymentStatus)
+        target.paymentStatus = result.paymentStatus;
+    if (result.deliveryStatus)
+        target.deliveryStatus = result.deliveryStatus;
+    if (result.verificationStatus)
+        target.verificationStatus = result.verificationStatus;
+    if (result.evidence?.length)
+        target.evidence.push(...result.evidence);
+    target.updatedAt = new Date().toISOString();
+    return { milestones: list, aggregate: aggregateMilestones(list), ok: true };
+}
+const REQUIRED_EVIDENCE_FIELDS = [
+    'quote', 'txHash', 'contentHash', 'envelopeDigest', 'failurePoint',
+];
+/** 开争议: 记录绑定的证据 + 缺口; 生命周期进 disputed (自动化到此为止) */
+export function buildDispute(opts) {
+    const missing = REQUIRED_EVIDENCE_FIELDS.filter((f) => {
+        const v = opts.evidence[f];
+        if (v === undefined || v === null)
+            return true;
+        if (typeof v === 'string')
+            return v.trim().length === 0;
+        if (Array.isArray(v))
+            return v.length === 0;
+        if (typeof v === 'object')
+            return Object.values(v).every((x) => x === undefined || x === null || x === '');
+        return false;
+    });
+    const responsibility = opts.evidence.responsibility
+        || (opts.responsibilityEvidence ? deriveResponsibility(opts.responsibilityEvidence) : undefined);
+    return {
+        openedAt: new Date().toISOString(),
+        reason: opts.reason,
+        evidence: { ...opts.evidence, responsibility },
+        missingEvidence: missing,
+        mustNotRepay: true,
+    };
+}
+/** 争议禁令的唯一实现在 settlement-state (`disputeForbids`), 这里只做转发, 避免两份判断漂移 */
+export { disputeForbids } from './settlement-state.js';
+/** 争议收尾: 必须带决定 + 依据 + 证据 (退款走结算层 refund_pending → refunded) */
+export function resolveDispute(rec, opts) {
+    if (!rec.dispute)
+        throw new Error('这笔交易没有争议记录');
+    if (!opts.evidence?.length)
+        throw new Error('争议收尾必须带证据 (不许无凭据关闭)');
+    return {
+        ...rec.dispute,
+        resolution: { decision: opts.decision, at: new Date().toISOString(), by: opts.by, reason: opts.reason, evidence: [...opts.evidence] },
+    };
+}
+/**
+ * 里程碑/争议叠加后的 Goal 成功证据门槛:
+ *   交易 verified 或 (全部里程碑完成 + 结算 fully_settled) ∧ 无争议 ∧ 执行成功 ∧ 命中判据
+ *   —— `partially_settled` 一律不算 (leo: 不要让 partially_settled 直接进 Goal 成功证据)
+ */
+export function milestoneGoalEligibility(rec, opts = {}) {
+    if (rec.dispute && !rec.dispute.resolution)
+        return { eligible: false, reason: '交易在争议中 (未收尾) → 不计入 Goal 成功证据' };
+    const agg = aggregateMilestones(rec.milestones);
+    if (agg.total > 0) {
+        if (agg.shouldDispute)
+            return { eligible: false, reason: '里程碑有失败项 → 需争议处理, 不计入成功证据' };
+        if (!agg.allComplete)
+            return { eligible: false, reason: `里程碑未全部完成 (${agg.verified}/${agg.total}) → partially_settled 不计入成功证据` };
+    }
+    if (rec.settlementFact === 'partially_settled')
+        return { eligible: false, reason: '结算事实是 partially_settled → 不计入成功证据' };
+    if (rec.status !== 'verified')
+        return { eligible: false, reason: `交易状态是 ${rec.status}, 不是 verified` };
+    if (rec.chainSettled !== true)
+        return { eligible: false, reason: '链上没有真实结算' };
+    if (opts.executionOk !== true)
+        return { eligible: false, reason: '资源执行没成功 (买到 ≠ 用上)' };
+    if (opts.goalCriteriaHit !== true)
+        return { eligible: false, reason: '没有命中 Goal 判据' };
+    return { eligible: true, reason: '链上结算 + 全部里程碑完成 + 无争议 + 执行成功 + 命中判据' };
+}

package/dist/agents/x402/paid-info-store.js

@@ -166,12 +166,23 @@ export async function checkAndSettlePayment(opts) {
     const req = opts.requirements.accepts[0];
     const network = String(req.network);
     if (!opts.paymentHeader)
-        return { ok: false, mode: 'none', error: '缺少 X-PAYMENT 头 (未付款)' };
+        return { ok: false, mode: 'none', error: '缺少 X-PAYMENT 头 (未付款)', attempted: false };
     const payload = decodePaymentHeader(opts.paymentHeader);
     if (!payload)
-        return { ok: false, mode: 'none', error: 'X-PAYMENT 不是合法 base64 JSON' };
+        return { ok: false, mode: 'none', error: 'X-PAYMENT 不是合法 base64 JSON', attempted: false };
     const facilitatorUrl = opts.facilitatorUrl ?? process.env.BOLLOON_X402_FACILITATOR ?? '';
     const allowLocalDev = opts.allowLocalDev ?? (process.env.BOLLOON_X402_LOCAL_VERIFY === '1');
+    // ★ 凭据绑定校验必须在**分模式之前** (两种模式都查): 拿旧回执去换另一条资源 → 一律拒绝。
+    //   真跑抓到过: 这段原来只对 local-dev 生效, facilitator 模式提前 return → 跨资源复用没被拦。
+    const boundItem = payload?.accepted?.extra?.itemId || payload?.accepted?.itemId || payload?.itemId;
+    if (opts.expectedItemId) {
+        if (!boundItem) {
+            return { ok: false, mode: 'none', attempted: false, error: '支付凭据没有绑定 itemId: 无法证明这笔钱是为这条资源付的' };
+        }
+        if (String(boundItem) !== String(opts.expectedItemId)) {
+            return { ok: false, mode: 'none', attempted: false, error: `支付凭据绑定的资源 (${boundItem}) 与本次请求 (${opts.expectedItemId}) 不一致 — 回执不能跨资源复用` };
+        }
+    }
     if (facilitatorUrl) {
         const f = opts.fetchImpl ?? fetch;
         const body = { x402Version: 2, paymentPayload: payload, paymentRequirements: req };
@@ -181,26 +192,28 @@ export async function checkAndSettlePayment(opts) {
             });
             const v = await vres.json();
             if (!v?.isValid) {
-                return { ok: false, mode: 'facilitator', error: `facilitator 校验未通过: ${v?.invalidReason || v?.invalidMessage || 'unknown'}` };
+                return { ok: false, mode: 'facilitator', attempted: true, verifyRejected: true, settlementUncertain: false, error: `facilitator 校验未通过: ${v?.invalidReason || v?.invalidMessage || 'unknown'}` };
             }
             const sres = await f(`${facilitatorUrl.replace(/\/$/, '')}/settle`, {
                 method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
             });
             const s = await sres.json();
             if (!s?.success) {
-                return { ok: false, mode: 'facilitator', error: `结算失败: ${s?.errorReason || s?.errorMessage || 'unknown'}` };
+                // settle 失败: 链上可能已经动了钱 → 不确定 (不是"没付过")
+                return { ok: false, mode: 'facilitator', attempted: true, verifyRejected: false, settlementUncertain: true, error: `结算失败: ${s?.errorReason || s?.errorMessage || 'unknown'}` };
             }
             const receipt = encodePaymentResponse(s);
-            return { ok: true, mode: 'facilitator', receipt, txHash: s.transaction, payer: s.payer || v.payer, network };
+            return { ok: true, mode: 'facilitator', receipt, txHash: s.transaction, payer: s.payer || v.payer, network, attempted: true };
         }
         catch (e) {
-            return { ok: false, mode: 'facilitator', error: `facilitator 不可达: ${String(e?.message || e).slice(0, 160)}` };
+            return { ok: false, mode: 'facilitator', attempted: true, verifyRejected: false, settlementUncertain: true, error: `facilitator 不可达: ${String(e?.message || e).slice(0, 160)}` };
         }
     }
     if (!allowLocalDev) {
         return {
             ok: false,
             mode: 'none',
+            attempted: false,
             error: '未配置 facilitator (BOLLOON_X402_FACILITATOR), 也未开启本机联调模式 (BOLLOON_X402_LOCAL_VERIFY=1) — 无法校验真实付款',
         };
     }
@@ -227,9 +240,14 @@ export async function checkAndSettlePayment(opts) {
  * 购买一条信息: 未付款时服务端回 402, 这里用标准 x402 客户端 (402→签名→重试) 完成支付。
  * 无钱包私钥时, 只有显式 allowLocalDev 才走本机联调头。
  */
+function makeTracker(onEvent) {
+    return async (e) => { if (onEvent)
+        await onEvent(e).catch(() => null); };
+}
 export async function buyInfo(params) {
     const { verifyEnvelope } = await import('./paid-info-protocol.js');
     const doFetch = params.fetchImpl ?? fetch;
+    const trackEvent = makeTracker(params.onEvent);
     // ① 先探一次: 判断是否 402 (以及免费信息直接返回)
     let res;
     try {
@@ -248,11 +266,22 @@ export async function buyInfo(params) {
         }
         return { ok: false, status: res.status, error: `服务端返回 ${res.status}: ${text.slice(0, 200)}` };
     }
-    // ② 402 → 支付 → 重试
+    // ② 402 → (策略门) → 支付 → 重试
     const requirementBody = safeJson(await res.text());
     const requirements = requirementBody?.accepts?.[0];
     if (!requirements)
         return { ok: false, status: 402, error: '402 响应缺少 accepts' };
+    const metadata = requirementBody?.metadata || requirementBody?.item || null;
+    await trackEvent({ kind: 'payment_required', detail: `amount=${requirements.amount} network=${requirements.network}` });
+    // Phase 2: 策略门 —— 必须在解密钱包/签名/付款之前 (顺序不可颠倒)
+    if (params.prePayGuard) {
+        const gate = await params.prePayGuard({ requirements, url: params.url });
+        if (!gate.ok) {
+            await trackEvent({ kind: 'policy_denied', detail: gate.reason });
+            return { ok: false, status: 402, policyDenied: true, error: gate.reason || '策略拒绝', metadata, raw: JSON.stringify(requirementBody) };
+        }
+        await trackEvent({ kind: 'policy_allowed', detail: '策略通过, 允许进入付款' });
+    }
     let paymentHeader = '';
     let mode = '';
     if (params.privateKey) {
@@ -264,16 +293,32 @@ export async function buyInfo(params) {
             maxPaymentAmount: params.maxPaymentAmount,
             rpcUrl: params.rpcUrl,
         });
+        // ★ 真把付款凭据发出去了 → 结算事实 payment_submitted (这一步之后失败都不能当"没付过钱")
+        await trackEvent({ kind: 'payment_sending', detail: 'facilitator 模式: 已发出 x402 付款请求', patch: { settlementFact: 'payment_submitted' } });
         const retry = await paymentFetch(params.url, { method: 'GET' });
         const text = await retry.text();
         const parsed = safeJson(text);
         const receipt = retry.headers.get('x-payment-response') || parsed?.payment?.receipt || '';
         if (retry.status < 200 || retry.status >= 300) {
-            return { ok: false, status: retry.status, error: `付款后重试失败 ${retry.status}: ${text.slice(0, 200)}` };
+            // 付款这一步已经发出去了 (可能已上链), 只是拿资源失败 → 绝不许当"没付过钱"
+            return {
+                ok: false, status: retry.status,
+                payment: { mode: 'facilitator', receipt: receipt || undefined, attempted: true, settled: true, settlementUncertain: !receipt },
+                error: `付款后重试失败 ${retry.status}: ${text.slice(0, 200)}`,
+            };
         }
         mode = 'facilitator';
+        // ★ 链上事实需要 txHash: facilitator 说成功但没有 txHash → 不能标 chainSettled (真跑抓到过这类"假结算")
+        const txHash = parsed?.payment?.txHash || retry.headers.get('x-payment-txhash') || parsed?.txHash || '';
+        await trackEvent({
+            kind: 'settled',
+            detail: `mode=facilitator receipt=${receipt.slice(0, 24)}… txHash=${txHash ? `${String(txHash).slice(0, 16)}…` : '(缺失: 不能认定链上结算完成)'}`,
+            patch: { paymentMode: 'facilitator', paymentReceipt: receipt, chainSettled: !!txHash, ...(txHash ? { txHash: String(txHash) } : {}) },
+        });
         const report = parsed?.proof ? await verifyEnvelope(parsed, { resolveDid: params.resolveDid, expectItemId: params.expectItemId }) : undefined;
-        return { ok: true, status: retry.status, envelope: parsed, verify: report, payment: { mode, receipt }, raw: text };
+        if (report)
+            await trackEvent({ kind: 'delivered', detail: `trust=${report.trust}`, patch: { verificationTrust: report.trust, contentHash: parsed?.contentHash, protocolVerified: report.trust === 'verified' } });
+        return { ok: true, status: retry.status, envelope: parsed, verify: report, payment: { mode, receipt }, metadata, raw: text };
     }
     if (!params.allowLocalDev) {
         return { ok: false, status: 402, error: '需要钱包私钥才能支付 (未提供 privateKey; 本机联调请显式 allowLocalDev)' };
@@ -284,17 +329,26 @@ export async function buyInfo(params) {
         payload: { localDev: true, at: new Date().toISOString() },
         payer: 'local-dev',
     }), 'utf-8').toString('base64');
+    await trackEvent({ kind: 'payment_sending', detail: 'local-dev 模式: 已发出 X-PAYMENT 请求 (非链上)', patch: { settlementFact: 'payment_submitted' } });
     const retry = await doFetch(params.url, { method: 'GET', headers: { 'X-PAYMENT': paymentHeader } });
     const text = await retry.text();
     const parsed = safeJson(text);
     if (retry.status < 200 || retry.status >= 300) {
-        return { ok: false, status: retry.status, error: `本机联调付款被拒 ${retry.status}: ${text.slice(0, 200)}` };
+        return {
+            ok: false, status: retry.status,
+            payment: { mode: 'local-dev', attempted: true, settled: false, settlementUncertain: false },
+            error: `本机联调付款被拒 ${retry.status}: ${text.slice(0, 200)}`,
+        };
     }
     mode = 'local-dev';
+    const receiptLd = retry.headers.get('x-payment-response') || parsed?.payment?.receipt || '';
+    await trackEvent({ kind: 'settled', detail: 'mode=local-dev (非链上)', patch: { paymentMode: 'local-dev', paymentReceipt: receiptLd, chainSettled: false } });
     const report = parsed?.proof ? await verifyEnvelope(parsed, { resolveDid: params.resolveDid, expectItemId: params.expectItemId }) : undefined;
+    if (report)
+        await trackEvent({ kind: 'delivered', detail: `trust=${report.trust} (本机联调)`, patch: { verificationTrust: report.trust, contentHash: parsed?.contentHash, protocolVerified: report.trust !== 'unverified' } });
     return {
-        ok: true, status: retry.status, envelope: parsed, verify: report,
-        payment: { mode, receipt: retry.headers.get('x-payment-response') || parsed?.payment?.receipt }, raw: text,
+        ok: true, status: retry.status, envelope: parsed, verify: report, metadata,
+        payment: { mode, receipt: receiptLd, attempted: true }, raw: text,
     };
 }
 function safeJson(text) {