@seasonkoh/webaz 0.1.28 → 0.1.29

package/dist/layer0-foundation/L0-2-state-machine/transitions.js

@@ -20,6 +20,43 @@ export const VALID_TRANSITIONS = {
         requiresEvidence: false,
         description: '下单后付款前取消订单'
     },
+    // ── Direct Pay (Rail 1) 直付:只"支付"这一步变,之后汇入既有流程 ──────────────
+    //   设计稿 docs/modules/DIRECT-PAYMENT-MODULE-DESIGN.INTERNAL.md §4。
+    //   本金(货款)不经协议;协议不验证付款;买家声明已付款 → 汇入 accepted(卖家发货)。
+    'created→direct_pay_window': {
+        allowedRoles: ['system'], // 直付下单路由锁定卖家费用质押后,以 system 显式推进(非超时驱动)
+        requiresEvidence: false,
+        description: 'Rail1 直付:卖家已质押平台费、展示收款方式,进入付款窗口'
+    },
+    'direct_pay_window→accepted': {
+        allowedRoles: ['buyer'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:买家声明"我已付款" → 汇入既有流程(卖家发货);协议不验证付款,谎报则卖家不发货(零损失自纠正)'
+    },
+    'direct_pay_window→cancelled': {
+        allowedRoles: ['buyer', 'system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:付款前买家取消(或卖家请求取消经买家确认)→ 释放费用质押'
+    },
+    'direct_pay_window→direct_expired_unconfirmed': {
+        // deadlineField 供【专属 cron(direct-pay-timeouts.ts)】读取;故意【不设 autoFaultState】→
+        // 通用 engine.checkTimeouts(需 deadlineField+autoFaultState 两者)绝不触发本转移,避免漏掉释放质押等副作用。
+        allowedRoles: ['system'],
+        deadlineField: 'direct_pay_window_deadline',
+        requiresEvidence: false,
+        description: 'Rail1 直付:付款窗口超时未标记 → 不静默关单,转可争议态(专属 cron 释放费用质押 + 停用收款指令)'
+    },
+    'direct_expired_unconfirmed→disputed': {
+        allowedRoles: ['buyer'],
+        requiresEvidence: true,
+        evidenceHint: '上传付款凭证(证据分级:链上 tx / 银行回执 / 截图)',
+        description: 'Rail1 直付:买家"我确实付了" → 升级争议(证据级信誉裁决,本档无资金赔付)'
+    },
+    'direct_expired_unconfirmed→cancelled': {
+        allowedRoles: ['buyer', 'system'],
+        requiresEvidence: false,
+        description: 'Rail1 直付:买家确认未付 / 宽限期后系统关单(终态)'
+    },
     // ── 卖家接单 ──────────────────────────────────────────────
     'paid→accepted': {
         allowedRoles: ['seller'],
@@ -243,6 +280,8 @@ export const CURRENT_RESPONSIBLE = {
     in_transit: 'logistics', // 等物流投递
     delivered: 'buyer', // 等买家确认
     disputed: 'arbitrator', // 等仲裁处理
+    direct_pay_window: 'buyer', // Rail1: 等买家付款并标记
+    direct_expired_unconfirmed: 'buyer', // Rail1: 等买家确认未付 或 升级争议
 };
 /** Phase 1 self-fulfill 覆盖表：seller 一人承担 shipped/picked_up/in_transit 全程 */
 export const CURRENT_RESPONSIBLE_SELF_FULFILL = {
@@ -275,6 +314,8 @@ export const ORDER_STATE_MEANINGS = {
     refunded_full: { zh: '仲裁裁全额退款,订单作废(终态)', en: 'arbitration full refund, order voided (terminal)' },
     dispute_dismissed: { zh: '争议被驳回(无效,终态)', en: 'dispute dismissed (terminal)' },
     expired: { zh: '订单超时自动失败(通用兜底,终态)', en: 'order expired (generic timeout, terminal)' },
+    direct_pay_window: { zh: 'Rail1 直付:已质押平台费,等买家付款(协议不持货款)', en: 'Rail1 direct-pay: fee-staked, awaiting buyer off-protocol payment (protocol holds no funds)' },
+    direct_expired_unconfirmed: { zh: 'Rail1 直付:付款窗口超时未标记(不静默关单,留争议/确认窗口)', en: 'Rail1 direct-pay: payment window expired unmarked (not silently closed; dispute/confirm window open)' },
 };
 /** 订单/争议生命周期契约 —— 集成方 agent 读它即懂"订单怎么流转 + 每步谁驱动 + 何时 + 含义"。 */
 export function orderLifecycleContract() {

package/dist/layer0-foundation/L0-5-manifest/manifest.js

@@ -303,7 +303,7 @@ async function getLiveStats() {
         const disputes = await n('SELECT COUNT(*) as n FROM disputes');
         const skills = await n("SELECT COUNT(*) as n FROM skills WHERE active = 1");
         const totalVolume = ((await dbOne("SELECT COALESCE(SUM(total_amount),0) as v FROM orders WHERE status = 'completed'"))?.v ?? 0);
-        return { users, active_products: products, total_orders: orders, completed_orders: completed, total_disputes: disputes, active_skills: skills, total_volume_dcp: totalVolume };
+        return { users, active_products: products, total_orders: orders, completed_orders: completed, total_disputes: disputes, active_skills: skills, total_volume_waz: totalVolume };
     }
     catch {
         return null;

package/dist/layer1-agent/L1-1-mcp-server/cli.js

@@ -0,0 +1,64 @@
+/**
+ * MCP 命令行标志(--version / --help / --mode / --doctor)。
+ *
+ * 目的:让人 / 陌生 agent 在【不启动 stdio server】的前提下验证安装、看清运行模式与真网络可达性。
+ * 无标志 → cliQuickResponse 返回 null,mcp.ts 照常启动 server(既有 MCP 客户端从不传 argv → 零破坏)。
+ * 模式判定复用 resolveMode(network-mode.ts)—— 与 server.ts 同一真相源,--mode/--doctor 报的就是 server 实际用的。
+ */
+import { SOFTWARE_VERSION } from '../../version.js';
+import { resolveMode } from './network-mode.js';
+const HELP = `webaz — WebAZ MCP server (@seasonkoh/webaz)
+
+Usage:
+  npx @seasonkoh/webaz            start the MCP stdio server (what MCP clients invoke)
+  npx @seasonkoh/webaz --version  print version and exit
+  npx @seasonkoh/webaz --mode     print the resolved run mode and exit
+  npx @seasonkoh/webaz --doctor   print mode + config + live-network reachability, then exit
+  npx @seasonkoh/webaz --help     show this help
+
+Modes (RFC-003):
+  network            WEBAZ_API_KEY set — can transact on the live webaz.xyz network
+  network_readonly   no key (DEFAULT) — public reads hit live webaz.xyz; transactions need a key
+  sandbox            explicit WEBAZ_MODE=sandbox — local SQLite, isolated from the live network
+
+Env:
+  WEBAZ_API_KEY   your api_key (get one at https://webaz.xyz/#welcome). Set → network mode.
+  WEBAZ_MODE      force a mode: network | network_readonly | sandbox (sandbox is opt-in only)
+  WEBAZ_API_URL   network endpoint (default https://webaz.xyz)`;
+/** 同步、纯:处理 --version/-v · --help/-h · --mode。命中 → 返回要打印的字符串;无这些标志 → null(mcp.ts 照常启动 server)。 */
+export function cliQuickResponse(argv, env) {
+    const has = (...names) => names.some(n => argv.includes(n));
+    if (has('--version', '-v'))
+        return SOFTWARE_VERSION;
+    if (has('--help', '-h'))
+        return HELP;
+    if (has('--mode'))
+        return resolveMode(env);
+    return null;
+}
+/** --doctor:模式 + 配置 + 真网络可达性。fetch 可注入便于测试;5s 超时保护,绝不 hang。sandbox 不探网络。 */
+export async function runDoctor(env, fetchImpl = fetch) {
+    const mode = resolveMode(env);
+    const url = (env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
+    const hasKey = !!(env.WEBAZ_API_KEY ?? '');
+    const lines = [
+        `webaz doctor — @seasonkoh/webaz v${SOFTWARE_VERSION}`,
+        `  mode:          ${mode}`,
+        `  api_key:       ${hasKey ? 'set (network transactions enabled)' : 'not set (network read-only; set WEBAZ_API_KEY to transact)'}`,
+        `  api_url:       ${url}`,
+    ];
+    if (mode === 'sandbox') {
+        lines.push('  reachability:  skipped (sandbox = local SQLite, isolated from the live network)');
+        return lines.join('\n');
+    }
+    let reach;
+    try {
+        const r = await fetchImpl(`${url}/api/protocol-status`, { signal: AbortSignal.timeout(5000) });
+        reach = r.ok ? `ok (${url} reachable, HTTP ${r.status})` : `degraded (HTTP ${r.status})`;
+    }
+    catch (e) {
+        reach = `unreachable (${e.message})`;
+    }
+    lines.push(`  reachability:  ${reach}`);
+    return lines.join('\n');
+}

package/dist/layer1-agent/L1-1-mcp-server/network-mode.js

@@ -7,6 +7,17 @@
  * the predicate so the gate decision is unit-testable without booting the stdio
  * server. (Extracted from server.ts; behavior unchanged except adding webaz_pair.)
  */
+/**
+ * 解析运行模式(纯函数,单一真相源 —— server.ts 的 MODE + CLI 的 --mode/--doctor 都用它,杜绝漂移)。
+ * 显式 WEBAZ_MODE(network|network_readonly|sandbox)优先;否则有 api_key → network,无 key → network_readonly。
+ * sandbox 只能显式设置(无 key 【不】回落 sandbox)。key 的真伪判定与 server.ts 一致(WEBAZ_API_KEY ?? '' 的真值性)。
+ */
+export function resolveMode(env) {
+    const m = (env.WEBAZ_MODE ?? '').toLowerCase();
+    if (m === 'network' || m === 'sandbox' || m === 'network_readonly')
+        return m;
+    return (env.WEBAZ_API_KEY ?? '') ? 'network' : 'network_readonly';
+}
 // Tools that talk to the live webaz.xyz network (Bearer api_key where needed).
 // Un-listed tools run sandbox (local). `_mode` annotation = network for these.
 export const NETWORK_TOOLS = new Set([

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -13,8 +13,8 @@
  *   webaz_wallet        查看钱包余额
  *   …（39 工具,完整定义见下方 TOOLS 数组;数量以 TOOLS.length 为准）
  *
- * 双模(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ SANDBOX(本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
- * 关联 / Related: AGENTS.md · RFC-003(双模) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
+ * 三态(RFC-003):NETWORK(WEBAZ_API_KEY → 调 webaz.xyz)/ NETWORK 只读(无 key,公共读走 webaz.xyz)/ SANDBOX(仅 WEBAZ_MODE=sandbox,本机库);见 NETWORK_TOOLS / apiCall / toolBackend。
+ * 关联 / Related: AGENTS.md · RFC-003(三态:network / network_readonly / sandbox) · RFC-004(webaz_feedback) · 元规则 #4 不撒谎(_mode 戳) /
  *   #6 不滥用(agent 责任制 + Iron-Rule 真人动作)· 生产端点在 src/pwa(NETWORK 共用)
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -25,7 +25,7 @@ import { initDatabase, generateId } from '../../layer0-foundation/L0-1-database/
 import { setSeamDb } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(本进程注入)
 import { applyWebazRuntimeSchema } from '../../runtime/apply-webaz-runtime-schema.js'; // 与 PWA 同源的纯 schema 桥(防 MCP fresh DB 漂移)
 import { generateCodeVerifier, pkceChallengeS256 } from '../../runtime/agent-pairing.js'; // RFC-020 PR-C1 — PKCE 配对
-import { NETWORK_TOOLS, NETWORK_SELF_AWARE, toolAllowedInNetworkMode } from './network-mode.js'; // RFC-003 网络门(可单测)
+import { NETWORK_TOOLS, NETWORK_SELF_AWARE, toolAllowedInNetworkMode, resolveMode } from './network-mode.js'; // RFC-003 网络门(可单测)+ 模式解析(单一真相源)
 import { homedir } from 'node:os';
 import { join as pathJoin } from 'node:path';
 import { existsSync as fsExists, mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync } from 'node:fs';
@@ -45,7 +45,7 @@ const TELEMETRY_URL = process.env.WEBAZ_TELEMETRY_URL ?? 'https://webaz.xyz/api/
 // 2026-06-01: phase A pre-launch 默认 OFF(opt-in)— W8 public launch 时翻回 default ON + 加 README 披露段
 // Phase A pre-launch: telemetry default OFF (opt-in). Flip to default ON at W8 launch + add README disclosure section.
 const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() === 'on';
-// ─── RFC-003 P0: 双模(NETWORK / SANDBOX)骨架 ─────────────────────
+// ─── RFC-003 P0: 三态(network_readonly / network / sandbox)骨架 ─────────────────────
 // NETWORK = 带 api_key 调 webaz.xyz/api(加入共享生产网络);SANDBOX = 本地 SQLite(离线试玩,与全网隔离)。
 // P0 不迁移任何工具(NETWORK_TOOLS 为空)→ 一切仍走本地 = 零行为变化;P1/P2 逐个把工具名加入集合切到网络。
 const WEBAZ_API_URL = (process.env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
@@ -59,15 +59,12 @@ export function resolveMcpApiKey(args, envKey = WEBAZ_API_KEY) {
     const explicit = typeof args?.api_key === 'string' ? args.api_key.trim() : '';
     return explicit || envKey;
 }
-const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
 // 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 key → network_readonly(装完即见真网络)。
 // network_readonly(L1 onboarding,2026-06-08):无 key 默认。公共读匿名打 webaz.xyz(真 catalog/协议),
 //   需身份的写/读返回"设 WEBAZ_API_KEY(到 #welcome 申请邀请)"。离线本地 playground 改为【显式】 WEBAZ_MODE=sandbox。
 //   —— 治"装完=空沙盒劝退"的死首体验;route/guard 与 network 同路(见 isNetworkMode),只是无 Bearer + 文案不同。
-const MODE = WEBAZ_MODE_ENV === 'network' ? 'network'
-    : WEBAZ_MODE_ENV === 'sandbox' ? 'sandbox'
-        : WEBAZ_MODE_ENV === 'network_readonly' ? 'network_readonly'
-            : (WEBAZ_API_KEY ? 'network' : 'network_readonly');
+// 单一真相源:resolveMode(见 network-mode.ts),CLI 的 --mode/--doctor 用同一函数,杜绝漂移。
+const MODE = resolveMode(process.env);
 // network 或 network_readonly 都"走真网络"(后者无 Bearer)。sandbox 才是本地。
 const isNetworkMode = () => MODE === 'network' || MODE === 'network_readonly';
 const recentCalls = [];
@@ -1899,10 +1896,10 @@ async function handleInfo() {
                     ? '🟢 NETWORK（只读）：无 api_key。公共读（搜索/榜单/价格史/浏览）打 webaz.xyz 真网络（见 network_live）。要交易（注册/下单/上架等）请设 WEBAZ_API_KEY —— 到 ' + WEBAZ_API_URL + '/#welcome 申请邀请。'
                     : '🟡 SANDBOX：所有工具都在本机本地 SQLite 运行，与 webaz.xyz 全网隔离（显式 dev/demo 模式）。任何计数 / 账号 / 订单仅本机有效。不设 WEBAZ_MODE 则默认走真网络只读。',
             phase: 'pre_launch',
-            real_users_on_canonical: 0,
+            // 真实用户/规模【不在此硬编码】—— 网络模式下 network_live(上方,实时拉 /api/protocol-status)带有 real_users_on_canonical 真值。
             canonical_endpoint: 'https://webaz.xyz',
             economic_flow: 'simulated WAZ (test currency, 1 WAZ ≈ 1 USDC peg is a模拟基准, not a real exchange rate). No fiat/crypto settles yet.',
-            disclaimer: '本协议尚未公开上线,prod 真实用户≈0,无真实经济流转。下方 live_stats / 工具示例所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
+            disclaimer: '本协议尚未公开上线(pre-launch),无真实经济流转。真实用户/规模请以 network_live(本次从 webaz.xyz 实时拉取的 /api/protocol-status,含 real_users_on_canonical)为准;下方 live_stats / 工具示例的所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
         },
         description: 'WebAZ is a decentralized commerce protocol. Every transaction flows through a state machine; each state transition needs proof-of-action from the responsible party. Any timeout-without-action: protocol auto-rules default + executes remedy. / WebAZ 是去中心化商业协议;每笔交易通过状态机流转,每次状态转移需对应责任方的操作证明;超时未操作则协议自动判违约并执行处置。',
         // 给【终端用户/买家】的价值主张 —— 陌生 agent / 普通买家先要知道"对我有什么用",而非只读抽象 tagline + 技术 description。
@@ -1996,7 +1993,7 @@ function handleRegister(args) {
             ],
             register_url: WEBAZ_API_URL,
             why_not_agent_self_register: 'agent 自助注册会绕过邀请 / captcha / 真人 Passkey 责任制，破坏协议的可问责性（#6 不滥用 / CHARTER §4 I-5）。',
-            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（或清空 WEBAZ_API_KEY），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
+            want_to_try_offline_first: '只想离线试玩、暂不连网络？设环境变量 WEBAZ_MODE=sandbox（本机沙盒需显式开启；无 key 仍是 NETWORK 只读，不会进沙盒），webaz_register 会在本机沙盒建一个测试账号（仅本机有效）。',
         };
     }
     // ─── SANDBOX 模式：本机建测试账号（显著标注，仅本机有效，与 webaz.xyz 全网隔离）──
@@ -2524,8 +2521,8 @@ async function handleListProduct(args) {
       id, seller_id, title, description, price, stock, category, stake_amount,
       specs, brand, model, source_price,
       ship_regions, handling_hours, estimated_days, fragile,
-      return_days, return_condition, warranty_days
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?)
+      return_days, return_condition, warranty_days, currency
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, 'WAZ')
   `).run(id, user.id, args.title, args.description, price, args.stock ?? 1, args.category ?? null, stakeAmount, specsJson, args.brand ?? null, args.model ?? null, args.source_price != null ? Number(args.source_price) : null, args.ship_regions ?? '全国', args.handling_hours != null ? Number(args.handling_hours) : 24, estJson, args.fragile ? 1 : 0, args.return_days != null ? Number(args.return_days) : 7, args.return_condition ?? '', args.warranty_days != null ? Number(args.warranty_days) : 0);
     // 注：per-order stake 模型不在此 lock — 移到 place_order 时按订单总额锁
     // S2/S3/S4 新字段：通过 HTTP PUT 走标准校验路径（i18n 语言白名单 / origin_claims 4KB+sha256 / 库存阈值）
@@ -3713,13 +3710,18 @@ async function handleReferral(args) {
                 state = 'never_activated';
                 note = 'Rewards inactive — attributions recorded; commissions held in pending_commission_escrow (30d window per protocol_params.rewards_opt_in.escrow_days) until you activate via PWA #me.';
             }
-            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending'").get(userId);
-            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired'").get(userId);
+            // RFC-018: matures_at IS NULL = opt-out escrow only (clearing rows auto-mature; surfaced separately in PR3).
+            const pending = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NULL").get(userId);
+            const expired = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'expired' AND matures_at IS NULL").get(userId);
+            // RFC-018 clearing window: opted-in commission accrued but not yet matured into the wallet
+            // (matures_at NOT NULL). Distinct from opt-out escrow above — pure read, surfaced for the agent.
+            const clearing = db.prepare("SELECT COUNT(*) AS n, COALESCE(SUM(amount),0) AS total FROM pending_commission_escrow WHERE recipient_user_id = ? AND status = 'pending' AND matures_at IS NOT NULL").get(userId);
             return {
                 state,
                 opted_in: optIn === 1,
                 note,
                 pending_escrow: { count: pending.n, total_amount: pending.total },
+                clearing: { count: clearing.n, total_amount: clearing.total }, // RFC-018: accrued, maturing after the return window (not yet paid)
                 expired_to_charity: { count: expired.n, total_amount: expired.total },
                 spec: 'RFC-002 §3.5 — rewards / share-commission opt-in (RFC-002)',
             };

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 契约见上)
+}