@bolloon/bolloon-agent 0.4.25 → 0.4.27

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

@@ -0,0 +1,378 @@
+/**
+ * settlement-state.ts — 交易的两层状态 + 结算事实 + 责任候选 (Phase 0 冻结, 2026-09-18)
+ *
+ * leo 的规格 (`docs/design-layer2.md` + 2026-09-18 交易闭环完成批次):
+ *   生命周期 (这笔交易走到哪一步) 与 **结算事实** (钱到底动没动) 必须**分开记**,
+ *   否则表达不了这些真实组合:
+ *     `paying + payment_submitted`       → 发出去了, 还没有回执
+ *     `settled + fully_settled`          → 钱真到了, 但正文还没验
+ *     `settled + unknown`                → facilitator 说成了, 链上还没确认
+ *     `delivery_failed + fully_settled`  → 钱付了, 正文没交 → 不能重付, 只能追责
+ *
+ * 三条不可混淆的红线:
+ *   ① `local-dev` 永远不能产生 `fully_settled` (链上没动过钱)
+ *   ② `chainSettled !== true` 永远不能 `verified`
+ *   ③ 非法状态迁移**拒绝**并给出原因, **不静默修正**
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { sha256Hex } from './paid-info-protocol.js';
+// ── ① 生命周期 (10 态; 与 transaction-protocol 的 status 同一层) ─────────────
+export const LIFECYCLE_STATUSES = [
+    'discovered',
+    'quoted',
+    'policy_denied',
+    'payment_required',
+    'paying',
+    'settled',
+    'delivered',
+    'verified',
+    'delivery_failed',
+    'verification_failed',
+    'disputed', // Phase 4: 争议 — 自动化到此为止, 钱的归宿在结算层 (refund_pending/refunded)
+];
+/** 旧记录里可能存在、仍必须可读的状态 (迁移时保留原值, 不假装它从没出现过) */
+export const LEGACY_STATUSES = ['failed'];
+export function isLifecycleStatus(v) {
+    return typeof v === 'string' && LIFECYCLE_STATUSES.includes(v);
+}
+export function isKnownStatus(v) {
+    return isLifecycleStatus(v) || (typeof v === 'string' && LEGACY_STATUSES.includes(v));
+}
+/** 终态: 走进去就不再自动变化 (delivery_failed 不是"还能重付"的意思) */
+export const TERMINAL_LIFECYCLE = ['verified', 'delivery_failed', 'verification_failed', 'policy_denied', 'disputed'];
+/**
+ * 允许的迁移表。没列出来的**一律拒绝**。
+ * 特别注意两条容易走错的:
+ *   - `paying → payment_required` 只在对账确认"没有支付证据"时允许 (回退重试的唯一合法路径)
+ *   - `delivery_failed`/`verification_failed` 不能回到 `paying` (钱已经付过了)
+ */
+const LIFECYCLE_TRANSITIONS = {
+    // 免费资源没有付款环节 → discovered 可直接 delivered (但永远不会 verified)
+    discovered: ['quoted', 'delivered', 'failed', 'policy_denied'],
+    quoted: ['paying', 'payment_required', 'delivered', 'failed', 'policy_denied'],
+    policy_denied: [],
+    payment_required: ['paying', 'failed', 'policy_denied'],
+    // 付款中 → 结算/交付/验真各结果, 或"对账发现没付过"退回 payment_required
+    paying: ['settled', 'delivered', 'verified', 'delivery_failed', 'verification_failed', 'payment_required', 'failed', 'disputed'],
+    settled: ['delivered', 'verified', 'delivery_failed', 'verification_failed', 'disputed'],
+    delivered: ['verified', 'delivery_failed', 'verification_failed', 'disputed'],
+    verified: [],
+    delivery_failed: ['disputed'], // 付了钱但没交付 → 可以进争议
+    verification_failed: ['disputed'], // 验真不过 → 可以进争议
+    disputed: [], // 终态: 收尾只能通过 resolveDispute + 结算层退款状态
+    failed: [], // 旧状态: 终态
+};
+export function canTransitionLifecycle(from, to) {
+    if (!isKnownStatus(from))
+        return { ok: false, reason: `当前状态不可识别: ${from}` };
+    if (!isKnownStatus(to))
+        return { ok: false, reason: `目标状态不可识别: ${to}` };
+    if (from === to)
+        return { ok: true, noop: true };
+    const allowed = LIFECYCLE_TRANSITIONS[from] || [];
+    if (!allowed.includes(to)) {
+        const why = TERMINAL_LIFECYCLE.includes(from) ? ` (${from} 是终态, 不许再变)` : '';
+        return { ok: false, reason: `非法迁移 ${from} → ${to}${why}; 允许: ${allowed.length ? allowed.join(', ') : '(无, 终态)'}` };
+    }
+    return { ok: true };
+}
+/** 这笔记录是否**已经有支付证据** (付过钱 / 可能付过钱) */
+export function hasPaymentEvidence(rec) {
+    if (rec.chainSettled === true)
+        return true;
+    if (rec.txHash || rec.paymentReceipt)
+        return true;
+    const fact = String(rec.settlementFact || '');
+    if (isSettlementFact(fact) && fact !== 'unpaid' && fact !== 'unknown')
+        return true;
+    return false;
+}
+/** verified 的**硬证据**子集 (完整门见 evaluateVerifiedGate: 还要求正文在盘上 + 执行 + 判据) */
+export function checkVerifiedPreconditions(rec) {
+    if (rec.chainSettled !== true)
+        return { ok: false, reason: 'chainSettled !== true: 链上没有真实结算, 不能判 verified (联调最高 delivered)' };
+    if (rec.protocolVerified !== true)
+        return { ok: false, reason: 'protocolVerified !== true: 协议验真未通过' };
+    if (!rec.contentHash || !rec.deliveryHash)
+        return { ok: false, reason: '缺少内容哈希或交付哈希' };
+    if (rec.contentHash !== rec.deliveryHash)
+        return { ok: false, reason: '内容哈希与交付哈希不一致 (内容被换过)' };
+    if (!rec.receiptHash)
+        return { ok: false, reason: '缺少支付回执哈希 (回执与信封未绑定)' };
+    const fact = String(rec.settlementFact || '');
+    if (fact && fact !== 'fully_settled' && fact !== 'partially_settled') {
+        return { ok: false, reason: `结算事实是 ${fact}, 不足以判 verified` };
+    }
+    return { ok: true };
+}
+/**
+ * 争议的三条禁令 (Phase 4, leo 原话): 不能自动重付 · 不能标 verified · **不能静默关闭**。
+ * 纯函数 + 无外部依赖, 所以写路径 (`checkLifecycleMove`) 和验收都能直接用同一份判断。
+ */
+export function disputeForbids(rec, target) {
+    const d = rec.dispute;
+    if (!d)
+        return { ok: true };
+    if (target === 'paying' || target === 'payment_required') {
+        return { ok: false, reason: '争议期间不允许重新付款 (禁令 1: 不能自动重付)' };
+    }
+    if (target === 'verified') {
+        return { ok: false, reason: '争议期间不允许标 verified (禁令 2: 争议不能标成功)' };
+    }
+    if (!d.resolution && String(rec.status) === 'disputed') {
+        return { ok: false, reason: '争议只能通过 resolveDispute 显式收尾 (禁令 3: 不能静默关闭)' };
+    }
+    return { ok: true };
+}
+/**
+ * 记录级的迁移许可 (在 from→to 表之上再加两条安全规则):
+ *   ① 已经有支付证据的交易**不许**被标成普通 `failed` (钱不能凭空消失) → 该记 delivery_failed / verification_failed, 或回 payment_required 走对账
+ *   ② 目标 `verified` 必须过硬证据子集 (链上结算 + 协议验真 + 哈希 + 回执绑定)
+ */
+export function checkLifecycleMove(rec, to) {
+    const base = canTransitionLifecycle(String(rec.status), to);
+    if (!base.ok)
+        return base;
+    if (base.noop)
+        return base;
+    const disputeCheck = disputeForbids(rec, to);
+    if (!disputeCheck.ok)
+        return disputeCheck;
+    if (to === 'failed' && hasPaymentEvidence(rec)) {
+        return { ok: false, reason: '这笔交易已有支付证据 (txHash/回执/链上结算) → 不许标成普通 failed; 应付交付失败用 delivery_failed, 验真失败用 verification_failed, 状态不明先回 payment_required 对账' };
+    }
+    if (to === 'verified') {
+        const pre = checkVerifiedPreconditions(rec);
+        if (!pre.ok)
+            return pre;
+    }
+    return { ok: true };
+}
+// ── ② 结算事实 (钱动没动; 与生命周期分开记) ──────────────────────────────────
+export const SETTLEMENT_FACTS = [
+    'unpaid',
+    'payment_submitted',
+    'payment_verified',
+    'partially_settled',
+    'fully_settled',
+    'refund_pending',
+    'refunded',
+    'unknown',
+];
+export function isSettlementFact(v) {
+    return typeof v === 'string' && SETTLEMENT_FACTS.includes(v);
+}
+const SETTLEMENT_TRANSITIONS = {
+    unpaid: ['payment_submitted', 'unknown'],
+    payment_submitted: ['payment_verified', 'partially_settled', 'unpaid', 'unknown'],
+    payment_verified: ['fully_settled', 'partially_settled', 'refund_pending', 'unknown'],
+    partially_settled: ['fully_settled', 'refund_pending', 'unknown'],
+    fully_settled: ['refund_pending'],
+    refund_pending: ['refunded', 'fully_settled'],
+    refunded: [],
+    unknown: ['unpaid', 'payment_submitted', 'payment_verified', 'partially_settled', 'fully_settled', 'refund_pending'],
+};
+/** 只有真链上/facilitator 确认过的结算事实 */
+export const CHAIN_BACKED_FACTS = ['payment_verified', 'partially_settled', 'fully_settled'];
+/** local-dev 能到的最高结算事实 (模拟提交 ≠ 链上事实) */
+export const LOCAL_DEV_MAX_FACT = 'payment_submitted';
+export function canTransitionSettlement(from, to, opts = {}) {
+    if (!isSettlementFact(from))
+        return { ok: false, reason: `当前结算事实不可识别: ${from}` };
+    if (!isSettlementFact(to))
+        return { ok: false, reason: `目标结算事实不可识别: ${to}` };
+    if (from === to)
+        return { ok: true, noop: true };
+    if (opts.paymentMode === 'local-dev' && CHAIN_BACKED_FACTS.includes(to)) {
+        return { ok: false, reason: `本机联调 (local-dev) 不能产生 ${to}: 链上没有真实结算, 联调最高只能是 ${LOCAL_DEV_MAX_FACT}` };
+    }
+    const allowed = SETTLEMENT_TRANSITIONS[from] || [];
+    if (!allowed.includes(to)) {
+        // 例外: 对账时拿到**链上事实** (txHash + chainSettled) 可以一步到位 fully_settled, 不必绕 payment_verified
+        const chainProof = opts.chainSettled === true && !!opts.txHash;
+        // ★ 例外只对"还没到链上口径"的事实生效; 退款状态是终态, 不许被链上证据绕回结算
+        //   (真跑抓到过: refunded → fully_settled 被这条例外放行 = 钱退出去又算结算)
+        const refundTerminal = from === 'refunded' || from === 'refund_pending';
+        if (to === 'fully_settled' && chainProof && !refundTerminal && !CHAIN_BACKED_FACTS.includes(from)) {
+            return { ok: true };
+        }
+        return { ok: false, reason: `非法结算迁移 ${from} → ${to}; 允许: ${allowed.length ? allowed.join(', ') : '(无, 终态)'}${to === 'fully_settled' ? ' (一步到 fully_settled 需要链上证据: chainSettled=true + txHash)' : ''}` };
+    }
+    return { ok: true };
+}
+/**
+ * 从记录既有证据**推导**结算事实 (给老记录迁移用; 不猜没有证据的事)。
+ * 推导不出确定事实时给 `unknown` —— 诚实表达"不知道钱动没动"。
+ */
+export function deriveSettlementFact(rec) {
+    const paid = ['paying', 'settled', 'delivered', 'verified', 'delivery_failed', 'verification_failed'].includes(String(rec.status));
+    if (rec.paymentMode === 'local-dev') {
+        // 联调: 有付款动作 → 最高只认"提交过(模拟)"; 没有 → 未付
+        return paid && (rec.paymentReceipt || rec.txHash) ? LOCAL_DEV_MAX_FACT : (paid ? 'unknown' : 'unpaid');
+    }
+    if (rec.chainSettled === true)
+        return String(rec.status) === 'verified' ? 'fully_settled' : 'payment_verified';
+    if (rec.txHash || rec.paymentReceipt)
+        return 'payment_submitted';
+    if (String(rec.status) === 'paying')
+        return 'unknown'; // 付过没付过不知道 → 先对账
+    return 'unpaid';
+}
+// ── ③ 责任候选 (机器只给候选, 不做最终赔偿判决) ─────────────────────────────
+export const RESPONSIBILITY_TYPES = [
+    'provider_fault',
+    'buyer_fault',
+    'agent_fault',
+    'platform_fault',
+    'payment_infrastructure_fault',
+    'undetermined',
+];
+/**
+ * 顺序即优先级: 先看"谁给的东西不对"(卖方), 再看"买方/agent 做错了什么",
+ * 再看基础设施, 最后证据不足认 `undetermined` —— 不许在证据不足时随便归责。
+ */
+export function deriveResponsibility(ev) {
+    const hits = [];
+    if (ev.deliveryHashMismatch) {
+        hits.push('deliveryHashMismatch');
+    }
+    if (ev.signatureInvalid) {
+        hits.push('signatureInvalid');
+    }
+    if (ev.outputSchemaViolation) {
+        hits.push('outputSchemaViolation');
+    }
+    if (hits.length) {
+        return {
+            type: 'provider_fault',
+            reason: `卖方交付物与声明不一致 (${hits.join(', ')})`,
+            evidence: hits,
+        };
+    }
+    if (ev.inputSchemaViolation) {
+        return { type: 'buyer_fault', reason: '输入不符合资源 inputSchema', evidence: ['inputSchemaViolation'] };
+    }
+    if (ev.policyBypassed) {
+        return { type: 'agent_fault', reason: 'agent 越过 Policy 付款/执行', evidence: ['policyBypassed'] };
+    }
+    if (ev.receiptMissing) {
+        return { type: 'payment_infrastructure_fault', reason: '缺少支付回执 (回执与信封未绑定)', evidence: ['receiptMissing'] };
+    }
+    if (ev.ledgerLostOrDoubleCharged) {
+        return { type: 'platform_fault', reason: '交易记录丢失或重复扣款', evidence: ['ledgerLostOrDoubleCharged'] };
+    }
+    if (ev.providerInfrastructureUnhealthy) {
+        return { type: 'payment_infrastructure_fault', reason: 'facilitator / RPC 状态异常', evidence: ['providerInfrastructureUnhealthy'] };
+    }
+    if (ev.deliveryMissing) {
+        return { type: 'undetermined', reason: '付了钱但没拿到正文: 传输或卖方未交付, 证据不足以定责', evidence: ['deliveryMissing'] };
+    }
+    if (ev.executionFailed) {
+        // 执行失败但交付物本身合契约 → 不足以归责卖方, 给不确定
+        return { type: 'undetermined', reason: '资源执行失败, 但证据不足以判归属', evidence: ['executionFailed'] };
+    }
+    return { type: 'undetermined', reason: '证据不足, 不做归责', evidence: [] };
+}
+// ── ④ 正文实体 (验真要能重新算哈希, 不是信一个布尔) ────────────────────────
+export function deliveriesDir(home) {
+    return path.join(home, '.bolloon', 'x402', 'deliveries');
+}
+function deliveryPath(transactionId, home) {
+    return path.join(deliveriesDir(home), `${transactionId}.txt`);
+}
+/** 交付正文落盘 (验真时重算哈希; 正文不进交易记录, 只进哈希与路径) */
+export function writeDeliveryContent(transactionId, content, home) {
+    const dir = deliveriesDir(home);
+    fs.mkdirSync(dir, { recursive: true });
+    const p = deliveryPath(transactionId, home);
+    const body = String(content ?? '');
+    fs.writeFileSync(p, body, 'utf8');
+    return { path: p, hash: sha256Hex(body), bytes: Buffer.byteLength(body, 'utf8') };
+}
+export function readDeliveryContent(transactionId, home) {
+    try {
+        return fs.readFileSync(deliveryPath(transactionId, home), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 正文真的在盘上, 且与我们交付时记下的**字节哈希**一致 (验真时重算, 不信记录里的自述)。
+ * 注意: 协议层的 contentHash/deliveryHash 是规范化哈希 (computeContentHash), 与字节哈希是两套,
+ * 各自独立校验, 不互相冒充。
+ */
+export function verifyDelivery(rec, home) {
+    const body = readDeliveryContent(rec.transactionId, home);
+    if (body === null)
+        return { present: false, matchesRecorded: false, reason: '交付正文不在盘上 (没交付, 或被删)' };
+    const bytesHash = sha256Hex(body);
+    const bytes = Buffer.byteLength(body, 'utf8');
+    const recorded = rec.deliveryBytesHash;
+    if (!recorded)
+        return { present: true, bytes, bytesHash, matchesRecorded: false, reason: '记录里没有交付字节哈希 (无法证明盘上正文就是当时交付的那份)' };
+    if (recorded !== bytesHash)
+        return { present: true, bytes, bytesHash, matchesRecorded: false, reason: `盘上正文哈希 ${bytesHash.slice(0, 12)}… ≠ 交付时记录 ${String(recorded).slice(0, 12)}…` };
+    return { present: true, bytes, bytesHash, matchesRecorded: true };
+}
+/**
+ * leo 的最终门: chainSettled + protocolVerified + 正文在 + 哈希对 + 回执绑定
+ *              + 资源执行成功 + 输出满足契约 + Goal 判据命中
+ */
+export function evaluateVerifiedGate(input) {
+    const { rec, home } = input;
+    const missing = [];
+    if (rec.chainSettled !== true)
+        missing.push('chainSettled !== true (链上没有真实结算)');
+    if (rec.protocolVerified !== true)
+        missing.push('protocolVerified !== true (协议验真没过)');
+    const delivery = verifyDelivery(rec, home);
+    if (!delivery.present)
+        missing.push('交付正文不存在');
+    else if (!delivery.matchesRecorded)
+        missing.push(`交付正文与交付时记录不一致 (${delivery.reason})`);
+    if (!rec.receiptHash)
+        missing.push('缺少支付回执哈希 (回执与信封未绑定)');
+    if (rec.settlementFact && rec.settlementFact !== 'fully_settled' && rec.settlementFact !== 'partially_settled') {
+        missing.push(`结算事实是 ${rec.settlementFact}, 不足以判 verified`);
+    }
+    // 显式传 null = 调用方明确说"这次没有执行证据"; 传 undefined = 用记录里已有的
+    const ex = input.execution !== undefined ? input.execution : (rec.execution ?? null);
+    if (!ex)
+        missing.push('没有资源执行证据');
+    else {
+        if (ex.ok !== true)
+            missing.push(`资源执行失败${ex.reason ? ` (${ex.reason})` : ''}`);
+        if (ex.schemaOk !== true)
+            missing.push('资源输出不满足 outputSchema');
+    }
+    if (input.goalCriteriaMet !== true)
+        missing.push('Goal 判据未命中');
+    if (missing.length)
+        return { verified: false, missing, reason: `未达 verified: ${missing[0]}` };
+    return { verified: true, missing: [], reason: '链上结算 + 协议验真 + 正文匹配 + 回执绑定 + 资源执行成功 + 输出合契约 + Goal 判据命中' };
+}
+// ── ⑥ 迁移 (老记录 → 两层; 事件与证据一个不丢) ──────────────────────────────
+export const CURRENT_SCHEMA_VERSION = 2;
+/**
+ * 幂等迁移: 补齐 `settlementFact` / `responsibility` / `schemaVersion`,
+ * 保留原 `status` 与**全部** events/evidence, 并追加一条 `migrate-v2` 事件说明推导来源。
+ * 不覆盖任何已有字段 (除了补默认值)。
+ */
+export function migrateTransactionRecord(input) {
+    const rec = { ...input, events: Array.isArray(input.events) ? [...input.events] : [] };
+    const before = input.schemaVersion;
+    if (before === CURRENT_SCHEMA_VERSION && isSettlementFact(rec.settlementFact)) {
+        return { record: rec, changed: false };
+    }
+    const derived = isSettlementFact(rec.settlementFact) ? rec.settlementFact : deriveSettlementFact(rec);
+    rec.settlementFact = derived;
+    rec.schemaVersion = CURRENT_SCHEMA_VERSION;
+    // 责任候选留空: 没有证据就不写归责 (迁移只补"结算事实"这一层)
+    const detail = before === undefined
+        ? `老记录迁移: 按既有证据推导结算事实 = ${derived} (status=${rec.status}, chainSettled=${rec.chainSettled === true}, mode=${rec.paymentMode})`
+        : `schema ${before} → ${CURRENT_SCHEMA_VERSION}: 结算事实 = ${derived}`;
+    rec.events.push({ at: new Date().toISOString(), kind: 'migrate-v2', detail });
+    return { record: rec, changed: true, note: detail };
+}

package/dist/agents/x402/trade.js

@@ -0,0 +1,257 @@
+/**
+ * trade.ts — 最小交易闭环编排 (Phase 1/2/4/5, 2026-09-16)
+ *
+ * 顺序固定 (不可颠倒):
+ *   发现报价 → Policy.check → 允许后才解密钱包 → 允许后才签名 → 发起 x402 支付
+ *    → 交付 → 验真 → 记录
+ *
+ * 任何一步失败都不许"看起来成功": 策略拒绝 → policy_denied (无签名/无链上交易/无扣预算/无交付);
+ * 付了钱但交付不合格 → delivery_failed; 交付了但验真不过 → verification_failed。
+ */
+import * as os from 'os';
+import { validatePaymentRequirements, evaluateTransactionSuccess, computeReceiptHash, } from './transaction-protocol.js';
+import { beginTransaction, updateTransaction, setTransactionStatus, setSettlementFact, readTransaction, findByRequestId, claimPayment, releasePaymentClaim } from './transaction-store.js';
+import { deriveResponsibility, writeDeliveryContent } from './settlement-state.js';
+export async function buyInfoAsTransaction(params) {
+    const home = params.home ?? os.homedir();
+    const doFetch = params.fetchImpl ?? fetch;
+    // 幂等: 同 requestId 已有交易 → 不再付第二次
+    const existing = await findByRequestId(params.requestId, home);
+    if (existing && ['settled', 'delivered', 'verified', 'delivery_failed', 'verification_failed'].includes(existing.status)) {
+        return { ok: existing.status === 'verified' || existing.status === 'delivered', status: existing.status, transactionId: existing.transactionId, record: existing, reused: true, error: existing.failureReason };
+    }
+    // ① 免费元数据 (不泄露正文; 用来做 itemId/payTo/network/币种 的预期校验)
+    let metadata = {};
+    let requirements = null;
+    let status = 402;
+    try {
+        const res = await doFetch(params.url, { method: 'GET' });
+        status = res.status;
+        const body = await res.json().catch(() => null);
+        if (res.status === 402) {
+            requirements = body?.accepts?.[0] || null;
+            // 元数据来源: 显式 metadata/item, 或从 402 要求的 extra 推导 (itemId/providerDid/category)
+            metadata = body?.metadata || body?.item || {
+                itemId: requirements?.extra?.itemId,
+                providerDid: requirements?.extra?.providerDid,
+                category: requirements?.extra?.category,
+                currency: requirements?.extra?.name,
+                network: requirements?.network,
+                payTo: requirements?.payTo,
+                amount: String(requirements?.amount ?? ''),
+            };
+        }
+        else if (body && (body.item || body.itemId)) {
+            metadata = body.item || body;
+        }
+    }
+    catch (e) {
+        const { record } = await beginTransaction({ requestId: params.requestId, metadata: {}, buyerDid: params.buyerDid, goalId: params.goalId, runId: params.runId }, home);
+        await setTransactionStatus(record.transactionId, 'failed', `请求失败: ${String(e?.message || e).slice(0, 120)}`, home);
+        const rec = await readTransaction(record.transactionId, home);
+        return { ok: false, status: 'failed', transactionId: record.transactionId, record: rec, error: `请求失败: ${String(e?.message || e).slice(0, 160)}` };
+    }
+    const { record, reused } = await beginTransaction({
+        requestId: params.requestId, metadata, buyerDid: params.buyerDid,
+        providerDid: metadata.providerDid, goalId: params.goalId, runId: params.runId,
+    }, home);
+    let rec = record;
+    // ★ 幂等短路: 这个 requestId 已经有交易走过付款流程 (或已结束) → 直接返回既有事实,
+    //   绝不重放"报价→付款"流程 (重放会既重复非幂等操作, 又踩非法迁移)。
+    if (reused && ['paying', 'settled', 'delivered', 'verified', 'delivery_failed', 'verification_failed', 'policy_denied', 'failed'].includes(String(record.status))) {
+        return {
+            ok: record.status === 'verified' || record.status === 'delivered',
+            status: record.status,
+            transactionId: record.transactionId,
+            record,
+            reused: true,
+            error: `该 requestId 已有交易处于 ${record.status} → 复用既有交易, 不重放付款`,
+        };
+    }
+    if (status !== 402) {
+        // 免费资源: 不算交易成功 (没有付款也就没有"结算")
+        rec = (await updateTransaction(rec.transactionId, { status: 'delivered', event: { kind: 'free_resource', detail: `HTTP ${status}` } }, home));
+        return { ok: true, status: 'delivered', transactionId: rec.transactionId, record: rec, reused };
+    }
+    // ② 报价自洽校验 (篡改 itemId/amount/payTo/network 一律拒绝)
+    const consistency = validatePaymentRequirements({
+        requirements,
+        metadata,
+        expected: { itemId: params.expectItemId, maxAmount: params.maxPaymentAmount, networks: params.expectNetworks },
+    });
+    if (!consistency.ok) {
+        rec = (await setTransactionStatus(rec.transactionId, 'failed', consistency.reason, home));
+        return { ok: false, status: 'failed', transactionId: rec.transactionId, record: rec, error: consistency.reason };
+    }
+    rec = (await updateTransaction(rec.transactionId, {
+        status: 'quoted', payTo: requirements.payTo, amount: String(requirements.amount), currency: requirements.currency || metadata.currency,
+        network: String(requirements.network), contentHash: metadata.contentHash, price: metadata.price,
+        event: { kind: 'quoted', detail: `amount=${requirements.amount} payTo=${String(requirements.payTo).slice(0, 10)}…` },
+    }, home));
+    // ③ 策略门 (Phase 2): 必须在解密/签名之前
+    const amountDecimal = Number(requirements.amount) / 1e6;
+    const service = params.service || 'x402-info';
+    let decision;
+    try {
+        const check = params.policyCheck || (async (intent) => {
+            const { getEconomicPolicy } = await import('../economic-policy.js');
+            return await getEconomicPolicy().check(intent);
+        });
+        decision = await check({ payTo: String(requirements.payTo), amount: amountDecimal, service });
+    }
+    catch (e) {
+        decision = { allowed: false, reason: `策略引擎不可用 (fail-closed): ${String(e?.message || e).slice(0, 120)}` };
+    }
+    // 任务预算 (独立于 policy 的第二道闸)
+    if (decision.allowed && params.taskBudget !== undefined) {
+        const budget = Number(params.taskBudget);
+        if (Number.isFinite(budget) && amountDecimal > budget) {
+            decision = { allowed: false, reason: `支付金额 ${amountDecimal} 大于任务预算 ${budget}` };
+        }
+    }
+    rec = (await updateTransaction(rec.transactionId, { policyDecision: decision, event: { kind: decision.allowed ? 'policy_allowed' : 'policy_denied', detail: decision.reason } }, home));
+    if (!decision.allowed) {
+        rec = (await setTransactionStatus(rec.transactionId, 'policy_denied', decision.reason, home));
+        return { ok: false, status: 'policy_denied', transactionId: rec.transactionId, record: rec, error: decision.reason || '策略拒绝' };
+    }
+    // ③.5 Phase 1: 抢"这笔 requestId 的付款权" (O_EXCL 独占, 跨进程唯一) —— 并发时只有一个能真付
+    const claim = await claimPayment(params.requestId, rec.transactionId, home);
+    if (!claim.ok) {
+        const prior = claim.record;
+        if (prior) {
+            rec = prior;
+            return { ok: prior.status === 'verified' || prior.status === 'delivered', status: prior.status, transactionId: prior.transactionId, record: prior, reused: true, error: claim.reason };
+        }
+        rec = (await setTransactionStatus(rec.transactionId, 'failed', claim.reason, home));
+        return { ok: false, status: rec.status, transactionId: rec.transactionId, record: rec, error: claim.reason };
+    }
+    rec = (await updateTransaction(rec.transactionId, { status: 'paying', event: { kind: 'paying', detail: `已取得付款权 (holder=${rec.transactionId}); 结算事实仍是 unpaid (还没真发出付款凭据)` } }, home));
+    // ④ 付款 + 交付 (仍然由 buyInfo 执行; 策略门已过才走到这里)
+    const { buyInfo } = await import('./paid-info-store.js');
+    const res = await buyInfo({
+        url: params.url,
+        privateKey: params.privateKey,
+        maxPaymentAmount: params.maxPaymentAmount,
+        network: params.network,
+        rpcUrl: params.rpcUrl,
+        allowLocalDev: params.allowLocalDev,
+        resolveDid: params.resolveDid,
+        expectItemId: params.expectItemId,
+        fetchImpl: params.fetchImpl,
+        prePayGuard: async () => ({ ok: true }), // 已在上一步过门 (这里不再重复打分)
+        onEvent: async (e) => {
+            const patch = { ...(e.patch || {}) };
+            // ★ 两层: 链上真的结算了 → 结算事实 payment_verified; 联调永远停 payment_submitted
+            if (patch.chainSettled === true && rec.paymentMode !== 'local-dev')
+                patch.settlementFact = 'payment_verified';
+            else if (patch.paymentReceipt && patch.paymentMode === 'local-dev')
+                patch.settlementFact = 'payment_submitted';
+            await updateTransaction(rec.transactionId, { ...patch, event: { kind: e.kind, detail: e.detail } }, home);
+        },
+    });
+    rec = (await readTransaction(rec.transactionId, home));
+    if (!res.ok) {
+        // ★ 钱不能凭空消失: 只要**发起过支付尝试**, 就不许记成普通 failed
+        //   结算不确定 → payment_required + unknown (先对账, 不许自动重付)
+        //   facilitator 明确拒绝 → payment_required + unpaid (钱一定没动, 可安全重试)
+        //   完全没付款凭据 → failed (此时确定没付过钱)
+        const attempted = res.payment?.attempted === true || !!rec.txHash || !!rec.paymentReceipt;
+        const uncertain = res.payment?.settlementUncertain === true;
+        const paidDone = res.payment?.settled === true || (!!rec.txHash && !uncertain);
+        let next;
+        if (res.policyDenied)
+            next = 'policy_denied';
+        else if (paidDone)
+            next = 'delivery_failed'; // 钱付了, 资源没到手
+        else if (uncertain)
+            next = 'payment_required'; // 可能付过 → 先对账, 不许自动重付
+        else if (attempted)
+            next = 'payment_required'; // 明确没付成 → 可安全重试
+        else
+            next = 'failed';
+        rec = (await updateTransaction(rec.transactionId, {
+            ...(uncertain ? { settlementFact: 'unknown' } : {}),
+            ...(paidDone ? { settlementFact: rec.chainSettled === true ? 'payment_verified' : 'payment_submitted' } : {}),
+            event: {
+                kind: 'payment_outcome',
+                detail: `attempted=${attempted} paidDone=${paidDone} uncertain=${uncertain} verifyRejected=${res.payment?.verifyRejected === true} → 状态 ${next}${uncertain ? ' (先对账, 不许自动重付)' : ''}`,
+            },
+        }, home));
+        rec = (await setTransactionStatus(rec.transactionId, next, res.error, home));
+        return { ok: false, status: rec.status, transactionId: rec.transactionId, record: rec, error: res.error };
+    }
+    await releasePaymentClaim(params.requestId, home).catch(() => null); // 付款完成 → 放锁 (事实已落盘)
+    // ⑤ 交付与验真绑定 (支付成功 ≠ 交易成功)
+    const envelope = res.envelope || null;
+    const content = String(envelope?.content ?? envelope?.body ?? '');
+    // 用协议同一套规范化哈希 (与卖方 contentHash 可比), 不是裸 sha256
+    const { computeContentHash } = await import('./paid-info-protocol.js');
+    const deliveryHash = computeContentHash(content);
+    const receiptStr = res.payment?.receipt || '';
+    // ★ 正文落盘: 让"资源正文存在 + 哈希正确"可以在事后**重新计算**验证, 而不是信记录里的自述
+    let deliveryBytes = null;
+    if (content) {
+        try {
+            const w = writeDeliveryContent(rec.transactionId, content, home);
+            deliveryBytes = { hash: w.hash, bytes: w.bytes };
+        }
+        catch {
+            deliveryBytes = null;
+        }
+    }
+    rec = (await updateTransaction(rec.transactionId, {
+        deliveryHash,
+        contentHash: envelope?.contentHash || envelope?.proof?.payload?.contentHash || envelope?.proof?.contentHash || rec.contentHash,
+        receiptHash: receiptStr ? computeReceiptHash(receiptStr) : undefined,
+        verificationTrust: res.verify?.trust || 'unverified',
+        protocolVerified: res.verify?.trust === 'verified',
+        ...(deliveryBytes ? { deliveryBytesHash: deliveryBytes.hash } : {}),
+        event: { kind: 'delivery_hash', detail: `deliveryHash=${deliveryHash.slice(0, 12)}… trust=${res.verify?.trust || 'unverified'}` },
+    }, home));
+    if (!content) {
+        const resp = deriveResponsibility({ deliveryMissing: true });
+        rec = (await updateTransaction(rec.transactionId, { responsibility: resp, event: { kind: 'responsibility_candidate', detail: `${resp.type}: ${resp.reason}` } }, home));
+        rec = (await setTransactionStatus(rec.transactionId, 'delivery_failed', '付了钱但没拿到正文', home));
+        return { ok: false, status: 'delivery_failed', transactionId: rec.transactionId, record: rec, verify: res.verify, error: '付了钱但没拿到正文' };
+    }
+    if (rec.contentHash && deliveryHash !== rec.contentHash) {
+        const resp = deriveResponsibility({ deliveryHashMismatch: true });
+        rec = (await updateTransaction(rec.transactionId, { responsibility: resp, event: { kind: 'responsibility_candidate', detail: `${resp.type}: ${resp.reason}` } }, home));
+        rec = (await setTransactionStatus(rec.transactionId, 'verification_failed', '内容哈希不匹配 (内容被换过)', home));
+        return { ok: false, status: 'verification_failed', transactionId: rec.transactionId, record: rec, verify: res.verify, error: '内容哈希不匹配' };
+    }
+    if (!rec.receiptHash) {
+        const resp = deriveResponsibility({ receiptMissing: true });
+        rec = (await updateTransaction(rec.transactionId, { responsibility: resp, event: { kind: 'responsibility_candidate', detail: `${resp.type}: ${resp.reason}` } }, home));
+        rec = (await setTransactionStatus(rec.transactionId, 'verification_failed', '缺少支付回执 (回执与信封未绑定)', home));
+        return { ok: false, status: 'verification_failed', transactionId: rec.transactionId, record: rec, verify: res.verify, error: '缺少支付回执' };
+    }
+    if ((rec.verificationTrust || 'unverified') === 'unverified') {
+        const ev = { signatureInvalid: true };
+        const resp = deriveResponsibility(ev);
+        rec = (await updateTransaction(rec.transactionId, { responsibility: resp, event: { kind: 'responsibility_candidate', detail: `${resp.type}: ${resp.reason}` } }, home));
+        rec = (await setTransactionStatus(rec.transactionId, 'verification_failed', `验真不通过 (${res.verify?.trust})`, home));
+        return { ok: false, status: 'verification_failed', transactionId: rec.transactionId, record: rec, verify: res.verify, error: `验真不通过: ${res.verify?.trust}` };
+    }
+    // ⑥ 终态: 链上结算 + 全部条件 → verified; 本机联调 → delivered (明确不许冒充 verified)
+    const verdict = evaluateTransactionSuccess({ ...rec, status: 'delivered' });
+    const finalStatus = verdict.success ? 'verified' : 'delivered';
+    rec = (await setTransactionStatus(rec.transactionId, finalStatus, verdict.reason, home));
+    if (finalStatus === 'verified') {
+        rec = (await setSettlementFact(rec.transactionId, 'fully_settled', '链上结算 + 交付与验真全通过', home));
+    }
+    // Phase 3: 交易证据写进 Run (step + evidence) 与 Goal (仅在 verified + 执行成功 + 命中判据时计入成功证据)
+    let bridge = null;
+    if (params.runId || params.goalId) {
+        try {
+            const { bridgeTransactionToRunGoal } = await import('./goal-run-bridge.js');
+            bridge = await bridgeTransactionToRunGoal(rec, {
+                runId: params.runId, goalId: params.goalId,
+                executionOk: params.executionOk, goalCriteriaHit: params.goalCriteriaHit,
+                summary: rec.itemId,
+            });
+        }
+        catch (e) { /* 记账失败不改变交易事实 */ }
+    }
+    return { ok: true, status: finalStatus, transactionId: rec.transactionId, record: rec, verify: res.verify, envelope, reused, bridge };
+}