@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/layer3-trust/L3-1-dispute-engine/mutual-cancel.js

@@ -0,0 +1,156 @@
+import { transition } from '../../layer0-foundation/L0-2-state-machine/engine.js';
+import { toUnits, toDecimal } from '../../money.js';
+import { applyWalletDelta, walletUnits } from '../../ledger.js';
+export function initMutualCancelSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS mutual_cancel_proposals (
+    id            TEXT PRIMARY KEY,
+    order_id      TEXT NOT NULL,
+    dispute_id    TEXT NOT NULL,
+    proposed_by   TEXT NOT NULL,
+    counterparty  TEXT NOT NULL,
+    status        TEXT NOT NULL DEFAULT 'pending',  -- pending | accepted | declined | withdrawn
+    reason        TEXT,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+    resolved_at   TEXT,
+    resolved_by   TEXT
+  )`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_mutual_cancel_order ON mutual_cancel_proposals(order_id, status)`);
+}
+/** 载入订单+活跃争议,并判定 caller 是否当事方 + 订单是否处于可协商取消的状态。fail-closed。 */
+function loadCancellable(db, orderId, userId) {
+    const order = db.prepare('SELECT id, buyer_id, seller_id, status, payment_rail, total_amount, stake_backing, bid_stake_held FROM orders WHERE id = ?').get(orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    const role = userId === order.buyer_id ? 'buyer' : userId === order.seller_id ? 'seller' : null;
+    if (!role)
+        return { ok: false, error: '仅买卖双方可协商取消该订单', error_code: 'NOT_A_PARTY' };
+    if (order.status !== 'disputed')
+        return { ok: false, error: '仅争议中的订单可协商取消', error_code: 'ORDER_NOT_DISPUTED' };
+    const dispute = db.prepare("SELECT id, status FROM disputes WHERE order_id = ? AND status IN ('open','in_review') ORDER BY created_at DESC LIMIT 1").get(orderId);
+    if (!dispute)
+        return { ok: false, error: '该订单没有进行中的争议', error_code: 'NO_ACTIVE_DISPUTE' };
+    return { ok: true, order, dispute, role };
+}
+/** 当前 pending 提议(至多一条)。 */
+function pendingProposal(db, orderId) {
+    return db.prepare("SELECT id, proposed_by, counterparty, status, reason, created_at FROM mutual_cancel_proposals WHERE order_id = ? AND status = 'pending' ORDER BY created_at DESC LIMIT 1").get(orderId);
+}
+/** 提议协商取消。proposalId 由路由用 generateId 生成后传入(域模块不自造 id)。 */
+export function proposeMutualCancel(db, orderId, userId, reason, proposalId) {
+    const g = loadCancellable(db, orderId, userId);
+    if (!g.ok)
+        return g;
+    const existing = pendingProposal(db, orderId);
+    if (existing) {
+        if (existing.proposed_by === userId)
+            return { ok: false, error: '你已提议协商取消,正在等待对方确认', error_code: 'ALREADY_PROPOSED', proposal_id: existing.id };
+        return { ok: false, error: '对方已提议协商取消,请直接确认接受', error_code: 'COUNTERPARTY_ALREADY_PROPOSED', proposal_id: existing.id };
+    }
+    const counterparty = g.role === 'buyer' ? g.order.seller_id : g.order.buyer_id;
+    db.prepare("INSERT INTO mutual_cancel_proposals (id, order_id, dispute_id, proposed_by, counterparty, status, reason) VALUES (?,?,?,?,?,'pending',?)")
+        .run(proposalId, orderId, g.dispute.id, userId, counterparty, (reason || '').slice(0, 500) || null);
+    return { ok: true, proposal_id: proposalId, status: 'pending' };
+}
+/** 提议方撤回自己的 pending 提议。 */
+export function withdrawMutualCancel(db, orderId, userId) {
+    const prop = pendingProposal(db, orderId);
+    if (!prop)
+        return { ok: false, error: '没有待处理的协商取消提议', error_code: 'NO_PENDING_PROPOSAL' };
+    if (prop.proposed_by !== userId)
+        return { ok: false, error: '只能撤回自己提出的提议', error_code: 'NOT_PROPOSER' };
+    db.prepare("UPDATE mutual_cancel_proposals SET status='withdrawn', resolved_at=datetime('now'), resolved_by=? WHERE id=?").run(userId, prop.id);
+    return { ok: true, status: 'withdrawn' };
+}
+/** 对方拒绝 pending 提议。 */
+export function declineMutualCancel(db, orderId, userId) {
+    const g = loadCancellable(db, orderId, userId);
+    if (!g.ok)
+        return g;
+    const prop = pendingProposal(db, orderId);
+    if (!prop)
+        return { ok: false, error: '没有待处理的协商取消提议', error_code: 'NO_PENDING_PROPOSAL' };
+    if (prop.proposed_by === userId)
+        return { ok: false, error: '不能拒绝自己的提议(如需取消请撤回)', error_code: 'CANNOT_DECLINE_OWN' };
+    db.prepare("UPDATE mutual_cancel_proposals SET status='declined', resolved_at=datetime('now'), resolved_by=? WHERE id=?").run(userId, prop.id);
+    return { ok: true, status: 'declined' };
+}
+/**
+ * 资金+状态结算(tx-free core)——【必须由路由用 db.transaction 包裹】。
+ *  · 直付(非托管):零资金,仅 transition→cancelled。
+ *  · 托管:买家托管货款退回(escrowed→balance);卖家【本订单实际锁定】的质押返还(staked→balance)。无罚没/手续费/信誉。
+ *  · 【money-path 铁律】买家退款 FAIL-CLOSED:实际 escrowed 必须 ≥ 本单全额,否则中止(不退/不关单/不结案),
+ *    绝不部分退款还静默收口。卖家质押返还取订单快照 stake_backing + bid_stake_held(不是商品名义 stake_amount ——
+ *    当前 escrow 模型 stake_backing 恒 0、不锁卖家 stake,bid_stake_held 仅中标单有),cap 到卖家真实 staked
+ *    (best-effort,不 fail-closed,以免卖家侧账目瑕疵卡死买家退款)。两侧都绝不打负 / 凭空印钱。
+ *  · 争议行同事务置 resolved(verdict='mutual_cancel'),防自动裁决二次结算。
+ */
+function settleMutualCancel(db, order, disputeId) {
+    const sys = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
+    if (!sys)
+        return { ok: false, error: 'sys_protocol 用户不存在', error_code: 'SYS_MISSING' };
+    const nonCustodial = order.payment_rail === 'direct_p2p';
+    let detail;
+    if (nonCustodial) {
+        detail = { non_custodial: true, buyer_refund: 0, seller_stake_returned: 0, note: '非托管(直付)单:协议不持货款 → 零资金,仅关单' };
+    }
+    else {
+        // 买家 made-whole 不可妥协 —— FAIL-CLOSED:买家实际 escrowed 必须 ≥ 本单全额,否则【中止】(不退、不关单、
+        //   不结案,留人工核对账目),绝不"部分退款还静默收口"。足额时退【本单全额】(escrowed≥total 保证退后 escrowed≥0,不超退)。
+        const totalU = toUnits(order.total_amount);
+        if (walletUnits(db, order.buyer_id).escrowed < totalU)
+            return { ok: false, error: '买家托管余额不足以全额退款,协商取消已中止(账目待人工核对)', error_code: 'ESCROW_INSUFFICIENT' };
+        applyWalletDelta(db, order.buyer_id, { escrowed: -totalU, balance: totalU });
+        // 卖家质押返还 = 尽力而为的抵押物返还(与买家退款不同、【不】fail-closed,以免卖家侧账目瑕疵卡死买家的无责退款):
+        //   只退【本订单快照锁定】的质押(stake_backing+bid_stake_held,非商品名义值),再 cap 到卖家真实 staked → 绝不打负/印钱。
+        const lockedU = toUnits(Number(order.stake_backing || 0)) + toUnits(Number(order.bid_stake_held || 0));
+        const stakeReturnU = Math.max(0, Math.min(lockedU, walletUnits(db, order.seller_id).staked));
+        if (stakeReturnU > 0)
+            applyWalletDelta(db, order.seller_id, { staked: -stakeReturnU, balance: stakeReturnU });
+        detail = { non_custodial: false, buyer_refund: toDecimal(totalU), seller_stake_returned: toDecimal(stakeReturnU), note: '托管单:买家全额退款(fail-closed 已验足额)+ 卖家本单锁定质押返还(cap 实际 staked);无罚没/手续费/信誉' };
+    }
+    const tr = transition(db, order.id, 'cancelled', sys.id, [], '双方协商取消(无责裁定:买家退款,双方信誉不受影响)');
+    if (!tr.success)
+        return { ok: false, error: tr.error, error_code: 'TRANSITION_FAILED' };
+    db.prepare("UPDATE disputes SET status='resolved', verdict='mutual_cancel', verdict_reason=?, ruling_type='mutual_cancel', resolved_at=datetime('now') WHERE id=?")
+        .run('双方合意取消订单 —— 无责终结,不计入任一方信誉', disputeId);
+    return { ok: true, settlement: { ...detail, terminal: 'cancelled', dispute: 'resolved', fault: 'none', reputation_impact: 'none' } };
+}
+/**
+ * 对方确认接受 → 执行协商取消。【路由必须 db.transaction 包裹本函数】。
+ * 事务内重新校验(competition-safe):当事方 + order 仍 disputed + 争议仍 open|in_review + 存在 pending 提议 + 非自我确认。
+ */
+export function acceptMutualCancel(db, orderId, userId) {
+    const g = loadCancellable(db, orderId, userId);
+    if (!g.ok)
+        return g;
+    const prop = pendingProposal(db, orderId);
+    if (!prop)
+        return { ok: false, error: '没有待确认的协商取消提议', error_code: 'NO_PENDING_PROPOSAL' };
+    if (prop.proposed_by === userId)
+        return { ok: false, error: '不能确认自己提出的取消,需由对方确认', error_code: 'CANNOT_ACCEPT_OWN' };
+    const settle = settleMutualCancel(db, g.order, g.dispute.id);
+    if (!settle.ok)
+        return settle;
+    db.prepare("UPDATE mutual_cancel_proposals SET status='accepted', resolved_at=datetime('now'), resolved_by=? WHERE id=?").run(userId, prop.id);
+    return { ok: true, status: 'accepted', settlement: settle.settlement };
+}
+/** UI 状态:当前提议 + 该 caller 可执行的动作。【party-gated】:非当事人一律 NOT_A_PARTY,绝不泄露提议/理由/发起方/存在性。 */
+export function getMutualCancelState(db, orderId, userId) {
+    const order = db.prepare('SELECT buyer_id, seller_id, status FROM orders WHERE id = ?').get(orderId);
+    if (!order)
+        return { ok: false, error: '订单不存在', error_code: 'ORDER_NOT_FOUND' };
+    if (userId !== order.buyer_id && userId !== order.seller_id)
+        return { ok: false, error: '仅买卖双方可查看协商取消状态', error_code: 'NOT_A_PARTY' }; // 读也 party-gate:不向非当事人泄露提议/理由/发起方
+    const hasActiveDispute = !!db.prepare("SELECT 1 FROM disputes WHERE order_id = ? AND status IN ('open','in_review') LIMIT 1").get(orderId);
+    const eligible = order.status === 'disputed' && hasActiveDispute;
+    const prop = pendingProposal(db, orderId);
+    const proposal = prop ? { id: prop.id, proposed_by: prop.proposed_by, reason: prop.reason, created_at: prop.created_at, mine: prop.proposed_by === userId } : null;
+    return {
+        ok: true,
+        proposal,
+        can_propose: eligible && !prop,
+        can_accept: eligible && !!prop && prop.proposed_by !== userId,
+        can_decline: eligible && !!prop && prop.proposed_by !== userId,
+        can_withdraw: eligible && !!prop && prop.proposed_by === userId,
+    };
+}

package/dist/layer4-economics/L4-4-skill-market/skill-engine.js

@@ -5,7 +5,7 @@
  * 核心思路：解决冷启动——现有 Amazon/Shopify 卖家零成本接入新渠道。
  *
  * Skill 类型：
- *   catalog_sync      - 目录同步（把外部店铺接入 DCP 搜索）
+ *   catalog_sync      - 目录同步（把外部店铺接入 WebAZ 搜索）
  *   auto_accept       - 自动接单（买家下单后立即接受，无需等待）
  *   price_negotiation - 价格协商（允许 Agent 在限定范围内议价）
  *   quality_guarantee - 质量承诺（额外质押，增强买家信心）
@@ -67,8 +67,8 @@ export const SKILL_TYPE_META = {
         label: '目录同步',
         label_en: 'Catalog sync',
         icon: '🔄',
-        description: '将卖家的外部商品目录（Amazon/Shopify/自定义）同步到 DCP，买家 Agent 订阅后可优先发现这些商品。',
-        description_en: 'Sync seller external catalogs (Amazon/Shopify/custom) to DCP — subscribed buyer agents discover these first.',
+        description: '将卖家的外部商品目录（Amazon/Shopify/自定义）同步到 WebAZ，买家 Agent 订阅后可优先发现这些商品。',
+        description_en: 'Sync seller external catalogs (Amazon/Shopify/custom) to WebAZ — subscribed buyer agents discover these first.',
     },
     auto_accept: {
         label: '自动接单',
@@ -95,7 +95,7 @@ export const SKILL_TYPE_META = {
         label: '质量承诺',
         label_en: 'Quality guarantee',
         icon: '🛡️',
-        description: '卖家额外质押 DCP 作为质量保证金，问题订单买家可获得额外赔偿。',
+        description: '卖家额外质押 WAZ 作为质量保证金，问题订单买家可获得额外赔偿。',
         description_en: 'Seller stakes extra WAZ as quality bond — buyer gets additional compensation on disputes.',
     },
     instant_ship: {

package/dist/ledger.js

@@ -1,9 +1,18 @@
 import { toUnits, toDecimal } from './money.js';
 /** 读某用户钱包当前余额(整数 base-units)。无钱包行 → 全 0。 */
 export function walletUnits(db, userId) {
-    const r = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked, COALESCE(escrowed,0) escrowed, COALESCE(earned,0) earned FROM wallets WHERE user_id = ?')
-        .get(userId);
-    return { balance: toUnits(r?.balance ?? 0), staked: toUnits(r?.staked ?? 0), escrowed: toUnits(r?.escrowed ?? 0), earned: toUnits(r?.earned ?? 0) };
+    // fee_staked 是 Direct Pay 新增列。向后兼容缺该列的库(迁移前 / 测试用最小 schema):
+    //   先按含 fee_staked 查;若该列不存在(no such column)→ 退回 4 列查,fee_staked=0。
+    let r;
+    try {
+        r = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked, COALESCE(escrowed,0) escrowed, COALESCE(earned,0) earned, COALESCE(fee_staked,0) fee_staked FROM wallets WHERE user_id = ?')
+            .get(userId);
+    }
+    catch {
+        r = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked, COALESCE(escrowed,0) escrowed, COALESCE(earned,0) earned FROM wallets WHERE user_id = ?')
+            .get(userId);
+    }
+    return { balance: toUnits(r?.balance ?? 0), staked: toUnits(r?.staked ?? 0), escrowed: toUnits(r?.escrowed ?? 0), earned: toUnits(r?.earned ?? 0), fee_staked: toUnits(r?.fee_staked ?? 0) };
 }
 /**
  * 对钱包字段施加整数单位 delta,以【绝对值】落库(读当前→加 delta→写 toDecimal)。

package/dist/mcp.js

@@ -4,12 +4,31 @@
  *
  * 运行:npm run mcp(或 npx @seasonkoh/webaz);通过 stdio 与 Claude 等 MCP 客户端通信。
  * 工具实现都在 src/layer1-agent/L1-1-mcp-server/server.ts(本文件只是 bootstrap)。
- * 双模:配 WEBAZ_API_KEY → NETWORK(调 webaz.xyz 共享网络);否则 SANDBOX(本机库)。详见 RFC-003。
+ * 模式:配 WEBAZ_API_KEY → NETWORK(可交易,调 webaz.xyz 共享网络);无 key → NETWORK 只读(公共读走 webaz.xyz);
+ *   仅 WEBAZ_MODE=sandbox 才用本机库(与全网隔离,dev/demo)。默认【不是】sandbox。详见 RFC-003。
  *
- * 关联 / Related: AGENTS.md(项目地图) · RFC-003(双模) · RFC-004(webaz_feedback)
+ * 关联 / Related: AGENTS.md(项目地图) · RFC-003(三态:network / network_readonly / sandbox) · RFC-004(webaz_feedback)
  */
-import { startMCPServer } from './layer1-agent/L1-1-mcp-server/server.js';
-startMCPServer().catch((err) => {
+// ⚠️ 只【静态】import cli.js(纯:version + network-mode,无副作用)。【不】静态 import server.js ——
+//   server.js 顶层会 initDatabase()/建 schema,静态 import 会让 --version/--help/--mode 也触发 DB 副作用
+//   (写 ~/.webaz/*.db)+ 加载整个 server(#186 审计 P1)。故 server.js 只在真正启动时【动态】import。
+import { cliQuickResponse, runDoctor } from './layer1-agent/L1-1-mcp-server/cli.js';
+async function main() {
+    const argv = process.argv.slice(2);
+    const quick = cliQuickResponse(argv, process.env); // --version / --help / --mode(纯,不碰 DB/server)
+    if (quick !== null) {
+        console.log(quick);
+        process.exit(0);
+    }
+    if (argv.includes('--doctor')) {
+        console.log(await runDoctor(process.env));
+        process.exit(0);
+    }
+    // 只有真正启动 stdio server 时才动态加载 server.js(此时才允许 DB 初始化等副作用)。
+    const { startMCPServer } = await import('./layer1-agent/L1-1-mcp-server/server.js');
+    await startMCPServer();
+}
+main().catch((err) => {
     console.error('MCP Server 启动失败：', err);
     process.exit(1);
 });

package/dist/merchant-bond-domain.js

@@ -0,0 +1,64 @@
+/**
+ * Merchant Base-Bond (v1 collateral-only) — domain skeleton (PR1, testnet/dev scaffold).
+ *
+ * 设计真相源:docs/modules/MERCHANT-BASE-BOND-DESIGN.INTERNAL.md(v1 candidate-locked)。
+ * 本模块是【纯域逻辑骨架】:状态机 + 资格派生 + 类型。**不写 DB、不接任何 live 路径、不碰资金。**
+ *
+ * v1 已锁(见设计稿 §12):
+ *  - 链上非托管锁仓合约持有 collateral;买家货款永不进合约;平台费【不上链】(链下账务)。
+ *  - slash 仅治理触发 + 链上硬约束(v1 无自动/小额 slash)。
+ *  - 合约 v1 不可升级;链 = Base + 白名单 USDC(单链);入门门 = 单一 base_bond_min_units(不分档)。
+ *  - wallet rotation = seller 签名 + WebAZ 授权;治理仅紧急。
+ *  - 计价用 base_bond_min_units(USDC 整数单位),不引预言机。
+ *
+ * ⚠️ MERCHANT_BOND_V1_ENABLED 默认 false:整套 v1 在 testnet/dev scaffold 阶段【关闭】,
+ *   mainnet + 真实 USDC 需先过 法务 + 外部合约审计 + Holden 批准(设计稿 §9)。
+ */
+/** 全局开关:v1 默认关闭(PR1 scaffold)。真实启用前永远 false。 */
+export const MERCHANT_BOND_V1_ENABLED = false;
+/** v1 链:Base + 白名单 USDC(单链;仅 chain profile 占位,无多链抽象)。 */
+export const MERCHANT_BOND_CHAIN_PROFILE = {
+    key: 'base',
+    // 真实 chainId / USDC 地址 / 确认数 N 在 mainnet 接入时由治理/配置定稿(政策参数);此处仅占位。
+    chainId: null,
+    usdcAddress: null,
+    minConfirmations: null,
+};
+/** Seller 生命周期状态(枚举;`paused` 不是 seller 状态,pause 是正交 flags)。 */
+export const BOND_STATUS = {
+    NONE: 'none',
+    PENDING_CONFIRMATIONS: 'pending_confirmations',
+    ACTIVE: 'active',
+    COOLING: 'cooling',
+    WITHDRAWABLE: 'withdrawable',
+    WITHDRAWN: 'withdrawn',
+    SLASHED_BELOW_MIN: 'slashed_below_min',
+};
+/** 合法状态转移(域层薄校验;真相仍以链上合约 event 为准)。 */
+const VALID_TRANSITIONS = {
+    [BOND_STATUS.NONE]: [BOND_STATUS.PENDING_CONFIRMATIONS],
+    [BOND_STATUS.PENDING_CONFIRMATIONS]: [BOND_STATUS.ACTIVE, BOND_STATUS.NONE],
+    [BOND_STATUS.ACTIVE]: [BOND_STATUS.COOLING, BOND_STATUS.SLASHED_BELOW_MIN],
+    [BOND_STATUS.COOLING]: [BOND_STATUS.WITHDRAWABLE, BOND_STATUS.ACTIVE],
+    [BOND_STATUS.WITHDRAWABLE]: [BOND_STATUS.WITHDRAWN, BOND_STATUS.ACTIVE],
+    [BOND_STATUS.WITHDRAWN]: [],
+    [BOND_STATUS.SLASHED_BELOW_MIN]: [BOND_STATUS.ACTIVE],
+};
+export function canTransitionBond(from, to) {
+    return (VALID_TRANSITIONS[from] || []).includes(to);
+}
+/**
+ * 资格派生(单一真相函数:readiness 与 create gate 必须都调它,定义逐字一致)。
+ * fail-closed:开关关 / 未绑钱包 / 未确认 / 状态非 active / 担保不足 → false。
+ * v1 入门门 = 单一 base_bond_min_units(不分档)。
+ */
+export function deriveSellerHasProductionBaseBondLocked(view, baseBondMinUnits) {
+    if (!MERCHANT_BOND_V1_ENABLED)
+        return false; // v1 scaffold 默认关 → 永远不翻真实资格
+    if (!view)
+        return false;
+    return view.walletBound
+        && view.confirmed
+        && view.status === BOND_STATUS.ACTIVE
+        && view.collateralUnits >= baseBondMinUnits;
+}

package/dist/merchant-bond-exposure.js

@@ -0,0 +1,78 @@
+import { toUnits } from './money.js';
+export const EXPOSURE_FACTOR_BPS_PARAM = 'direct_pay.exposure_factor_bps';
+export const EXPOSURE_FACTOR_BPS_DEFAULT = 8000;
+export class ExposureCapConfigError extends Error {
+}
+/** fail-closed 读取 factor:整数 ∈ [1,10000];缺失/非数/越界 → 抛 ExposureCapConfigError。 */
+export function readExposureFactorBps(getProtocolParam) {
+    const raw = getProtocolParam(EXPOSURE_FACTOR_BPS_PARAM, undefined);
+    const n = Number(raw);
+    if (raw === undefined || raw === null || raw === '' || !Number.isFinite(n) || !Number.isInteger(n) || n <= 0 || n > 10000) {
+        throw new ExposureCapConfigError(`${EXPOSURE_FACTOR_BPS_PARAM} invalid (got ${JSON.stringify(raw)}); must be integer in [1,10000]`);
+    }
+    return n;
+}
+/** 卖家当前有效抵押(USDC integer units,big-int 安全):merchant_bond_deposits status='active' 之和。无 → 0n。 */
+export function getActiveCollateralUnits(db, sellerId) {
+    let rows = [];
+    // 表缺失(旧/最小库)→ 视作无抵押(0n),休眠安全:不让缺表破坏现有直付建单。
+    try {
+        rows = db.prepare("SELECT collateral_units FROM merchant_bond_deposits WHERE seller_id = ? AND status = 'active'").all(sellerId);
+    }
+    catch {
+        return 0n;
+    }
+    let sum = 0n;
+    for (const r of rows) {
+        try {
+            sum += BigInt(r.collateral_units || '0');
+        }
+        catch { /* 坏行跳过,不计入(fail-closed:少算抵押更保守) */ }
+    }
+    return sum;
+}
+/**
+ * 开放敞口状态(未完全关闭的 direct_p2p 单)。终态【不】计入(释放敞口):
+ *   completed / cancelled / fault_* / resolved_for_seller / refunded_partial / refunded_full / dispute_dismissed / expired。
+ * ⚠️ direct_expired_unconfirmed 是【非终态】(超时不静默关单,仍可转 disputed / cancelled,见 transitions.ts)→ 必须计入,
+ *    漏算会低估敞口(对风险闸是危险方向)。created 为建单原子前态(direct_p2p 一般即转 window),防御性纳入(过度计入只会更严、无害)。
+ */
+export const OPEN_EXPOSURE_STATUSES = [
+    'created', 'direct_pay_window', 'direct_expired_unconfirmed',
+    'accepted', 'shipped', 'picked_up', 'in_transit', 'delivered', 'confirmed', 'disputed',
+];
+/** 卖家当前 Direct Pay 开放敞口(units):未完全关闭的 direct_p2p 单 total_amount 之和。 */
+export function computeDirectPayOpenExposureUnits(db, sellerId) {
+    const placeholders = OPEN_EXPOSURE_STATUSES.map(() => '?').join(',');
+    const rows = db.prepare(`SELECT total_amount FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND status IN (${placeholders})`).all(sellerId, ...OPEN_EXPOSURE_STATUSES);
+    let sum = 0n;
+    for (const r of rows)
+        sum += BigInt(toUnits(Number(r.total_amount) || 0));
+    return sum;
+}
+/** 纯函数:本单是否在敞口上限内。allowed = collateral × bps / 10000;open + new ≤ allowed。 */
+export function withinExposureCap(args) {
+    const allowed = args.activeCollateralUnits * BigInt(args.factorBps) / 10000n;
+    return args.openExposureUnits + args.newOrderUnits <= allowed;
+}
+/**
+ * create-gate 主入口。休眠安全:collateral==0 → ok(N/A,缓交路径由 deferral quota 管,不读 factor)。
+ * collateral>0 → 读 factor(fail-closed)+ 比较;超出 → 拒(EXPOSURE_CAP_EXCEEDED)。
+ */
+export function enforceCollateralExposureGate(db, sellerId, newOrderUnits, getProtocolParam) {
+    const collateral = getActiveCollateralUnits(db, sellerId);
+    if (collateral <= 0n)
+        return { ok: true }; // 无真实抵押 → 敞口上限不适用(休眠)
+    let factorBps;
+    try {
+        factorBps = readExposureFactorBps(getProtocolParam);
+    }
+    catch (e) {
+        return { ok: false, error_code: 'EXPOSURE_CAP_CONFIG', reason: e.message };
+    } // fail-closed
+    const openExposureUnits = computeDirectPayOpenExposureUnits(db, sellerId);
+    if (!withinExposureCap({ activeCollateralUnits: collateral, openExposureUnits, newOrderUnits: BigInt(newOrderUnits), factorBps })) {
+        return { ok: false, error_code: 'EXPOSURE_CAP_EXCEEDED', reason: 'direct-pay open exposure exceeds collateral-backed cap' };
+    }
+    return { ok: true };
+}

package/dist/merchant-bond-watcher.js

@@ -0,0 +1,26 @@
+/**
+ * Merchant Base-Bond — chain watcher skeleton (PR1, testnet/dev scaffold).
+ *
+ * 设计:docs/modules/MERCHANT-BASE-BOND-DESIGN.INTERNAL.md §4.1/§4.2。
+ * 职责(未来 testnet 才接真实 RPC):监听合约 deposit/slash/withdraw event → ≥N confirmations 后
+ *   更新 DB 镜像(merchant_bond_*)。reorg 后冻结派生资格 + 告警。
+ *
+ * ⚠️ PR1 阶段:**纯骨架、默认关、不连任何 RPC、不写资金、不接 live 路径。** 启用前需:
+ *   chain profile 定稿 + 法务 + 外部合约审计 + Holden 批准(设计稿 §9)。
+ */
+import { MERCHANT_BOND_V1_ENABLED, MERCHANT_BOND_CHAIN_PROFILE } from './merchant-bond-domain.js';
+/**
+ * 启动 watcher。**PR1:若未启用(默认)或 chain profile 未定稿 → 直接返回 no-op,绝不连 RPC。**
+ * 真实事件处理(deposit recognition / confirmations / reorg freeze)留待后续 testnet PR。
+ */
+export function startMerchantBondWatcher(_deps = {}) {
+    const profileReady = MERCHANT_BOND_CHAIN_PROFILE.chainId != null
+        && MERCHANT_BOND_CHAIN_PROFILE.usdcAddress != null
+        && MERCHANT_BOND_CHAIN_PROFILE.minConfirmations != null;
+    if (!MERCHANT_BOND_V1_ENABLED || !profileReady) {
+        // disabled scaffold:no RPC、no timer、no DB write。
+        return { enabled: false, stop: () => { } };
+    }
+    // 真实监听实现 = 后续 testnet PR(deposit/slash/withdraw event → ≥N confirmations → DB 镜像;reorg 冻结+告警)。
+    throw new Error('MerchantBondWatcher: real chain listening not implemented in PR1 scaffold');
+}

package/dist/payment-rails.js

@@ -0,0 +1,29 @@
+import { takeFeeAtCompletion, releaseFeeStake, slashFeeStakeToPenalty } from './direct-pay-ledger.js';
+/**
+ * Rail 1 = 非托管场外直付 + 信誉(buyer protection = reputation-only, refund = none)。
+ * ⚠️ 本 seam 当前【未接线】(getPaymentRail 无调用方)。Rail1 平台费【实时路径】= 首单宽限 + 预充值续用:
+ *   建单走【首单宽限 + 预充值门】(direct-pay-create.ts),完成时 accrue 应收(server.ts settleOrder direct_p2p 分支)。
+ *   下方 collectFeeAtCompletion/release/slash 仍指向旧 WAZ fee-stake helper = 遗留/forward-compat 占位;
+ *   若将来真接线本 seam,须改为应收/预充值语义(accrue / prepay)。
+ */
+export const RAIL_DIRECT_P2P = {
+    contract: {
+        id: 'direct_p2p',
+        buyerProtection: 'reputation_only',
+        refund: 'none',
+        disputeRemedyBasis: 'evidence_reputation',
+        custodialOfTradeFunds: false,
+    },
+    collectFeeAtCompletion: (db, orderId) => takeFeeAtCompletion(db, { orderId }),
+    releaseOnExpiryOrCancel: (db, orderId) => releaseFeeStake(db, { orderId }),
+    slashOnFault: (db, orderId, txnId, reason) => slashFeeStakeToPenalty(db, { orderId, txnId, reason }),
+};
+/**
+ * 取轨道实现。只 Rail 1 已实现;'escrow' 走既有系统(不经此抽象);'onchain_full_stake' / 'psp' = GATED(未实现)。
+ * 故意用显式 switch,不建插件注册框架(anti-YAGNI)。
+ */
+export function getPaymentRail(railId) {
+    if (railId === 'direct_p2p')
+        return RAIL_DIRECT_P2P;
+    return null; // escrow=既有系统; onchain_full_stake/psp=未实现(forward-compat 契约见上)
+}

package/dist/platform-receive-accounts.js

@@ -0,0 +1,94 @@
+import { validateQrDataUri } from './direct-receive-account-qr.js';
+import { MAX_INSTRUCTION_LEN, MAX_LABEL_LEN, MAX_METHOD_LEN, CURRENCY_RE } from './direct-receive-accounts.js';
+/** PURE:校验 + 规范化文本字段(trim / 长度 / 币种)。长度超限=显式拒(非静默截断)。 */
+export function normalizePlatformText(input) {
+    const instruction = String(input?.instruction ?? '').trim();
+    if (!instruction)
+        return { ok: false, reason: 'instruction required' };
+    if (instruction.length > MAX_INSTRUCTION_LEN)
+        return { ok: false, reason: `instruction must be ≤ ${MAX_INSTRUCTION_LEN} chars` };
+    const field = (v, max, name) => {
+        if (v == null)
+            return { ok: true, v: null };
+        const s = String(v).trim();
+        if (s.length > max)
+            return { ok: false, reason: `${name} must be ≤ ${max} chars` };
+        return { ok: true, v: s || null };
+    };
+    const L = field(input.label, MAX_LABEL_LEN, 'label');
+    if (!L.ok)
+        return L;
+    const M = field(input.method, MAX_METHOD_LEN, 'method');
+    if (!M.ok)
+        return M;
+    let currency = null;
+    if (input.currency != null && String(input.currency).trim()) {
+        currency = String(input.currency).trim().toUpperCase();
+        if (!CURRENCY_RE.test(currency))
+            return { ok: false, reason: 'currency must be a 2-8 char code (e.g. SGD, USDC)' };
+    }
+    return { ok: true, value: { instruction, label: L.v, method: M.v, currency } };
+}
+/** PURE:解析 qrDataUri 入参 → 'keep'(缺省不改) | null(清除) | 校验后的 data-uri | 错误。 */
+export function resolveQrInput(input) {
+    if (!('qrDataUri' in input) || input.qrDataUri === undefined)
+        return { ok: true, qr: 'keep' };
+    const q = input.qrDataUri;
+    if (q == null || String(q).trim() === '')
+        return { ok: true, qr: null }; // 清除
+    const v = validateQrDataUri(q);
+    if (!v.ok)
+        return { ok: false, reason: v.reason };
+    return { ok: true, qr: String(q).trim() };
+}
+const COLS = 'id, label, method, currency, instruction, qr_data_uri, status';
+/** 全部平台收款方式(默认仅 active;{ includeInactive:true } 取全部,含 qr_data_uri)。admin 用。 */
+export function listPlatformAccounts(db, opts = {}) {
+    const where = opts.includeInactive ? '' : " WHERE status = 'active'";
+    return db.prepare(`SELECT ${COLS} FROM platform_receive_accounts${where} ORDER BY created_at ASC, id ASC`).all();
+}
+/** 仅 active(卖家侧看:含 instruction + qr_data_uri —— 平台公开收款明细,非披露门)。 */
+export function listActivePlatformAccounts(db) {
+    return listPlatformAccounts(db, { includeInactive: false });
+}
+export function getPlatformAccount(db, id) {
+    return db.prepare(`SELECT ${COLS} FROM platform_receive_accounts WHERE id = ?`).get(id) ?? null;
+}
+/** 新增 active 平台收款方式。 */
+export function addPlatformAccount(db, input, generateId) {
+    const t = normalizePlatformText(input);
+    if (!t.ok)
+        return t;
+    const q = resolveQrInput(input);
+    if (!q.ok)
+        return q;
+    const qr = q.qr === 'keep' ? null : q.qr; // 新增时无既有值,'keep' 视作无 qr
+    const id = generateId('pra');
+    db.prepare(`INSERT INTO platform_receive_accounts (id, label, method, currency, instruction, qr_data_uri, status) VALUES (?,?,?,?,?,?, 'active')`)
+        .run(id, t.value.label, t.value.method, t.value.currency, t.value.instruction, qr);
+    return { ok: true, account: { id, status: 'active', qr_data_uri: qr, ...t.value } };
+}
+/** 更新(文本总更;qr 仅当入参给了 qrDataUri 才动 —— 缺省保留既有)。 */
+export function updatePlatformAccount(db, id, input) {
+    const t = normalizePlatformText(input);
+    if (!t.ok)
+        return t;
+    const q = resolveQrInput(input);
+    if (!q.ok)
+        return q;
+    const v = t.value;
+    let info;
+    if (q.qr === 'keep') {
+        info = db.prepare(`UPDATE platform_receive_accounts SET label=?, method=?, currency=?, instruction=?, updated_at=datetime('now') WHERE id=?`)
+            .run(v.label, v.method, v.currency, v.instruction, id);
+    }
+    else {
+        info = db.prepare(`UPDATE platform_receive_accounts SET label=?, method=?, currency=?, instruction=?, qr_data_uri=?, updated_at=datetime('now') WHERE id=?`)
+            .run(v.label, v.method, v.currency, v.instruction, q.qr, id);
+    }
+    return { ok: true, changed: info.changes > 0 };
+}
+/** 软停用(卖家不再看到)。 */
+export function deactivatePlatformAccount(db, id) {
+    return db.prepare("UPDATE platform_receive_accounts SET status='inactive', updated_at=datetime('now') WHERE id=? AND status='active'").run(id).changes > 0;
+}

package/dist/product-verification.js

@@ -0,0 +1,93 @@
+export const MAX_URL_LEN = 2048;
+export const MAX_PLATFORM_LEN = 60;
+export const MAX_NOTES_LEN = 500;
+const ACTIVE = "('issued','submitted','verified')";
+const getActiveForProduct = (db, productId) => db.prepare(`SELECT * FROM product_verifications WHERE product_id = ? AND status IN ${ACTIVE} ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(productId);
+/** http(s) 链接最弱校验(仅存储,不抓取):必须 http/https、长度受限。拒 javascript:/data: 等危险 scheme。 */
+function isStorableHttpUrl(url) {
+    if (typeof url !== 'string' || url.length === 0 || url.length > MAX_URL_LEN)
+        return false;
+    return /^https?:\/\/[^\s]+$/i.test(url.trim());
+}
+/** 卖家为【某产品】申请认证 → issued(签发 code)。绝不自动 verify。单一活跃(per product)。调用方须先校验 seller 拥有该产品。 */
+export function requestProductVerification(db, args) {
+    const { id, productId, sellerId, code } = args;
+    if (!id || !productId || !sellerId || !code)
+        return { ok: false, reason: 'missing id/productId/sellerId/code' };
+    const platform = args.platform ? String(args.platform).trim().slice(0, MAX_PLATFORM_LEN) : null;
+    const active = getActiveForProduct(db, productId);
+    if (active)
+        return { ok: false, reason: `该产品已有进行中的认证(${active.status})` };
+    db.prepare(`INSERT INTO product_verifications (id, product_id, seller_id, code, platform, status, created_at, updated_at)
+    VALUES (?,?,?,?,?, 'issued', datetime('now'), datetime('now'))`).run(id, productId, sellerId, code, platform);
+    return { ok: true, status: 'issued', code };
+}
+/** 卖家为【某产品】提交外部链接 → submitted。要求该产品有 issued 记录;链接仅存储(不抓取)。调用方须校验 seller 拥有该产品。 */
+export function submitProductVerificationLink(db, args) {
+    const url = String(args.externalUrl || '').trim();
+    if (!isStorableHttpUrl(url))
+        return { ok: false, reason: '请提交有效的 http(s) 商品链接' };
+    const active = getActiveForProduct(db, args.productId);
+    if (!active)
+        return { ok: false, reason: '请先为该产品申请认证获取验证码' };
+    if (active.status === 'verified')
+        return { ok: false, reason: '该产品认证已通过,无需重复提交' };
+    const platform = args.platform != null ? String(args.platform).trim().slice(0, MAX_PLATFORM_LEN) : active.platform;
+    db.prepare(`UPDATE product_verifications SET external_url = ?, platform = ?, status = 'submitted', updated_at = datetime('now') WHERE id = ?`)
+        .run(url, platform, active.id);
+    return { ok: true, status: 'submitted' };
+}
+/** 真人 admin 手动核对结论 → verified | rejected。仅从 submitted 流转。reviewerId 必填(责任分层;ROOT/Passkey 由调用方强制)。 */
+export function reviewProductVerification(db, args) {
+    const { id, reviewerId, decision } = args;
+    if (!reviewerId)
+        return { ok: false, reason: 'reviewProductVerification requires a human reviewerId' };
+    if (decision !== 'verified' && decision !== 'rejected')
+        return { ok: false, reason: 'decision must be verified|rejected' };
+    const row = db.prepare('SELECT * FROM product_verifications WHERE id = ?').get(id);
+    if (!row)
+        return { ok: false, reason: 'product verification not found' };
+    if (row.status === decision)
+        return { ok: true, status: decision, already: true };
+    if (row.status !== 'submitted')
+        return { ok: false, reason: `cannot review from status '${row.status}' (need submitted)` };
+    const notes = args.notes != null ? String(args.notes).slice(0, MAX_NOTES_LEN) : null;
+    db.prepare(`UPDATE product_verifications SET status = ?, reviewed_by = ?, reviewed_at = datetime('now'), notes = ?, updated_at = datetime('now') WHERE id = ?`)
+        .run(decision, reviewerId, notes, id);
+    return { ok: true, status: decision };
+}
+/** 某产品最新一条认证记录(任意状态)。无 → null。 */
+export function getProductVerification(db, productId) {
+    return db.prepare('SELECT * FROM product_verifications WHERE product_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1').get(productId) ?? null;
+}
+/** 某卖家所有产品认证记录(供卖家自助面板逐产品展示状态)。最新在前。 */
+export function listSellerProductVerifications(db, sellerId) {
+    return db.prepare('SELECT * FROM product_verifications WHERE seller_id = ? ORDER BY created_at DESC, rowid DESC').all(sellerId);
+}
+export function toSellerProductVerificationView(row) {
+    return {
+        id: row.id, product_id: row.product_id, code: row.code, platform: row.platform, external_url: row.external_url,
+        status: row.status, reviewed_at: row.reviewed_at, created_at: row.created_at, updated_at: row.updated_at,
+    }; // 故意省略 reviewed_by + notes(admin 身份 / 内部备注)
+}
+/** admin 队列:按 status 过滤(默认全部),最新在前。纯读。 */
+export function listProductVerifications(db, opts = {}) {
+    if (opts.status)
+        return db.prepare(`SELECT * FROM product_verifications WHERE status = ? ORDER BY created_at DESC, rowid DESC`).all(opts.status);
+    return db.prepare(`SELECT * FROM product_verifications ORDER BY created_at DESC, rowid DESC`).all();
+}
+/** 硬门读取:该产品是否【已验证】(有 verified 记录)。供 direct-pay create/availability 强制(未验证 → 不可直付)。 */
+export function productStoreVerified(db, productId) {
+    return !!db.prepare("SELECT 1 FROM product_verifications WHERE product_id = ? AND status = 'verified' LIMIT 1").get(productId);
+}
+/**
+ * 反作弊生命周期:商品发生【重大编辑】(标题/价格/详情/外部链接)时作废其验证 → status='stale'。
+ *   之后 productStoreVerified=false(硬门重新拦截),且 active 记录被清(卖家可重新申领→提交→admin 重核)。
+ *   防"先把商品 A 验证通过,再改标题/价格/详情/链接变成商品 B"绕过逐品门。返回作废条数。纯写,只改本表。
+ *   注:store-level 豁免卖家不依赖逐品验证,本作废对其直付资格无影响。
+ */
+export function invalidateProductVerification(db, productId) {
+    const r = db.prepare(`UPDATE product_verifications SET status = 'stale', updated_at = datetime('now')
+    WHERE product_id = ? AND status IN ('issued','submitted','verified')`).run(productId);
+    return { invalidated: r.changes };
+}