@seasonkoh/webaz 0.1.18 → 0.1.20

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

@@ -133,6 +133,28 @@ export function checkTimeouts(db) {
             }
         }
     }
+    // RFC-007 stage 3：终结【临时判责】的客观拒单 —— 举证窗口逾期仍无人仲裁 → 落定为违约结算。
+    //   (被仲裁接手的订单 stage 5 会清 pending / 改 disputed,不会命中此扫描;settled_fault_at 防重入。)
+    // 注:deadline 存为 SQLite datetime(空格)、now 为 JS ISO(带 T/Z),字符串直比会错(空格<T) → 两侧都用 datetime() 归一化。
+    const staleProvisional = db.prepare(`
+    SELECT id FROM orders
+    WHERE status = 'fault_seller' AND COALESCE(decline_objective_pending, 0) = 1
+      AND COALESCE(decline_contested, 0) = 0
+      AND settled_fault_at IS NULL
+      AND decline_contest_deadline IS NOT NULL AND datetime(decline_contest_deadline) < datetime(?)
+  `).all(now);
+    for (const o of staleProvisional) {
+        try {
+            const sys = getSystemUser(db);
+            settleFault(db, o.id, 'fault_seller');
+            transition(db, o.id, 'completed', sys.id, [], 'RFC-007：客观拒单举证窗口逾期未仲裁 → 终结为违约');
+            db.prepare('UPDATE orders SET decline_objective_pending = 0 WHERE id = ?').run(o.id);
+            details.push({ orderId: o.id, action: '临时判责 → fault_seller（举证逾期终结）' });
+        }
+        catch (e) {
+            console.error(`[decline finalize] order=${o.id}`, e);
+        }
+    }
     return { processed: details.length, details };
 }
 /**
@@ -186,7 +208,9 @@ export function getOrderStatus(db, orderId) {
 //   - fault_logistics→ buyer 全额退款 + seller stake 全额返还（卖家无责，物流坏账协议吸收）
 //   - fault_buyer    → 仅库存回退（escrow 未锁，无资金动作）
 // 不发放 commission / PV / 基金池入金 — 无真实成交
-function settleFault(db, orderId, faultState) {
+// export: 供 tests/test-fault-forfeit-conservation.ts 直接验证守恒(真实代码,非复刻)。
+//   生产仅由本模块 checkTimeouts 内部调用;导出不改变其调用语义。
+export function settleFault(db, orderId, faultState) {
     const sysUserId = 'sys_protocol';
     // 幂等检查 + 资金处置全部包在 transaction 内（防未来迁 PG 时并发 race）
     db.transaction(() => {
@@ -199,13 +223,98 @@ function settleFault(db, orderId, faultState) {
         const buyerId = order.buyer_id;
         const sellerId = order.seller_id;
         const isSecondhand = order.source === 'secondhand';
-        // QA 轮 7 P0 修复 — 改 per-order stake
-        // 旧逻辑读 product.stake_amount + stake_locked_at（per-product 模型残留，已废弃）
-        // 新逻辑：stake = order.total_amount × 0.15，下单时已锁，fault 时必然 lock（除非该订单未到 paid）
-        const sellerStakeRate = 0.15;
-        const stakeAmount = isSecondhand ? 0 : Math.round(total * sellerStakeRate * 100) / 100;
-        // 订单到 paid 之后 stake 必然 lock（place_order 已扣，余额不足会 reject）
-        const stakeLocked = !isSecondhand && Number(order.total_amount) > 0 && order.status !== 'created';
+        // RFC-008 stage 1（印钱 bug 修复）+ stage 2（罚没解耦）：
+        //   stage 1：违约没收按订单 stake_backing 快照,绝不假设已锁、绝不超背书 → 根治"staked 转负+印钱"bug。
+        //   stage 2：罚没率【与质押率解耦】—— penalty = fault_penalty_rate(默认 30%) × total,独立于 stake_rate。
+        //     · 背书订单(stake_backing>0)：先扣 staked(封顶背书额),不足再扣卖家【自由 balance】(责任自负,
+        //       罚没真可执行,不被薄质押架构性封顶)。
+        //     · 起步免赔付(require_seller_stake=0 → backing=0)：仍 0 没收,【绝不碰新商家自由余额】(否则重新引入
+        //       我们刚移除的门槛),买家已全额退款,卖家仅掉信誉。
+        //   守恒不变：实扣 F(staked+balance) === 分出去的 F(协议/买家/推广/公池),永不印钱、永不转负。
+        const faultPenaltyRate = () => {
+            const row = db.prepare("SELECT value FROM protocol_params WHERE key = 'fault_penalty_rate'").get();
+            const v = Number(row?.value);
+            return Number.isFinite(v) && v >= 0 ? v : 0.30;
+        };
+        const penaltyAmount = isSecondhand ? 0 : Math.round(total * faultPenaltyRate() * 100) / 100;
+        const orderStakeBacking = Math.max(0, Math.round(Number(order.stake_backing || 0) * 100) / 100);
+        // RFC-007 stage 4：没收后的【守恒 + 不牟利】再分配(取代旧的 buyer 50% / protocol 50%)。
+        //   旧分配漏掉推广人(违反 §谁责任谁承担:推广人承担了真实推广成本却零补偿)。
+        //   新规则(全部用订单快照,可复算,绝不印钱):
+        //     1. 协议只回收【原本该收的平台费】protocolTake = min(F, total × protocol_fee_rate)
+        //        —— 协议不从违约牟利;fund_base(1%) 排除(无成交=无 GMV,社区基金不应从罚没获利)。
+        //     2. R = F − protocolTake;买家补偿 = R × 50%(受损对手方固定份额)。
+        //     3. 推广人 = R 的另一半,按 l1/l2/l3 原始佣金比例分,【封顶各自原始佣金】—— 永不超过其真实损失。
+        //     4. 推广半残值(超封顶 / 无推广人)→ commission_reserve 三级公池(与正常单未归属佣金同去向,不给买家=不过补)。
+        //   守恒:protocolTake + buyerComp + promotersPaid + reserveResidual ≡ F(按构造,残值兜底)。
+        const FORFEIT_LEVEL_RATES = { 1: 0.70, 2: 0.20, 3: 0.10 };
+        const round2 = (n) => Math.round(n * 100) / 100;
+        const reserveResidual = (amount, note) => {
+            const a = round2(amount);
+            if (a <= 0)
+                return;
+            // 复制 redirectToCommissionReserve 的两笔写入(L0 不依赖 server.ts;kind 用既有 orphan_sponsor 桶)
+            db.prepare(`UPDATE commission_reserve SET balance = balance + ?, total_orphan_sponsor = total_orphan_sponsor + ?, updated_at = datetime('now') WHERE id = 'main'`).run(a, a);
+            db.prepare(`INSERT INTO commission_reserve_txns (id, kind, from_user_id, amount, related_order_id, note) VALUES (?,?,?,?,?,?)`)
+                .run(generateId('crt'), 'redirect_orphan_sponsor', sellerId, a, orderId, note);
+        };
+        const protocolFeeRate = () => {
+            const key = isSecondhand ? 'protocol_fee_rate_secondhand' : 'protocol_fee_rate_shop';
+            const row = db.prepare('SELECT value FROM protocol_params WHERE key = ?').get(key);
+            const v = Number(row?.value);
+            return Number.isFinite(v) && v >= 0 ? v : (isSecondhand ? 0.01 : 0.02);
+        };
+        // 罚没【收取 + RFC-007 守恒分配】,返回实扣额(= 0 表示起步免赔付,无没收无印钱)
+        const forfeitAndDistribute = (penalty) => {
+            // 起步免赔付:无背书订单(stake_backing=0)绝不没收、绝不碰新商家自由余额
+            if (orderStakeBacking <= 0)
+                return 0;
+            // stage 2 收取:先扣 staked(封顶背书额),不足部分再扣卖家自由 balance(责任自负;封顶其真实余额→不转负)
+            const fromStaked = Math.min(penalty, orderStakeBacking);
+            const remainder = round2(penalty - fromStaked);
+            const sellerBal = Math.max(0, Number(db.prepare('SELECT COALESCE(balance,0) AS b FROM wallets WHERE user_id = ?').get(sellerId)?.b ?? 0));
+            const fromBalance = round2(Math.min(remainder, sellerBal));
+            const F = round2(fromStaked + fromBalance);
+            if (F <= 0)
+                return 0;
+            if (fromStaked > 0)
+                db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(fromStaked, sellerId);
+            if (fromBalance > 0)
+                db.prepare('UPDATE wallets SET balance = balance - ? WHERE user_id = ?').run(fromBalance, sellerId);
+            // 1. 协议回收原始平台费(封顶 F,不牟利)
+            const protocolTake = round2(Math.min(F, total * protocolFeeRate()));
+            if (protocolTake > 0)
+                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(protocolTake, sysUserId);
+            // 2. R 与买家补偿
+            const R = round2(F - protocolTake);
+            const buyerComp = round2(R * 0.5);
+            if (buyerComp > 0)
+                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(buyerComp, buyerId);
+            // 3. 推广半 → l1/l2/l3 按原始佣金比例,封顶各自原始佣金
+            const promoterHalf = round2(R - buyerComp);
+            const commissionRate = Number(order.snapshot_commission_rate ?? 0);
+            const pool = round2(total * (Number.isFinite(commissionRate) && commissionRate > 0 ? commissionRate : 0));
+            const levels = [
+                { uid: order.l1_uid, orig: round2(pool * FORFEIT_LEVEL_RATES[1]) },
+                { uid: order.l2_uid, orig: round2(pool * FORFEIT_LEVEL_RATES[2]) },
+                { uid: order.l3_uid, orig: round2(pool * FORFEIT_LEVEL_RATES[3]) },
+            ].filter(l => l.uid); // 仅【真实存在的推广人】参与
+            const originalCommissionTotal = round2(levels.reduce((s, l) => s + l.orig, 0));
+            let promotersPaid = 0;
+            if (promoterHalf > 0 && originalCommissionTotal > 0) {
+                const payable = Math.min(promoterHalf, originalCommissionTotal); // 封顶原始佣金总额
+                for (const l of levels) {
+                    const share = round2(payable * (l.orig / originalCommissionTotal));
+                    if (share <= 0)
+                        continue;
+                    db.prepare('UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?').run(share, share, l.uid);
+                    promotersPaid = round2(promotersPaid + share);
+                }
+            }
+            // 4. 推广半残值(超封顶 / 无推广人 / 取整余数)→ 三级公池;绝不给买家、绝不印钱
+            reserveResidual(promoterHalf - promotersPaid, `RFC-007 fault forfeit residual order=${orderId}`);
+            return F;
+        };
         // P0.1：RFQ 路径的 bid_stake_held — fault 时由各分支按规则处理
         const bidStakeHeld = Number(order.bid_stake_held || 0);
         if (faultState === 'fault_seller') {
@@ -222,31 +331,9 @@ function settleFault(db, orderId, faultState) {
                 if (compToSys > 0)
                     db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compToSys, sysUserId);
             }
-            // 2. stake 50/50 扣罚（严格资金守恒：实扣多少就分多少，不允许协议印钱）
-            if (stakeAmount > 0) {
-                // 先确定实际可扣金额
-                let actualDeduct = 0;
-                if (stakeLocked) {
-                    // 已锁 → stake 全额扣（必然可扣，因 stake 已 lock 不可挪用）
-                    db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(stakeAmount, sellerId);
-                    actualDeduct = stakeAmount;
-                }
-                else {
-                    // 未锁 → 从 seller.balance 扣（不足则只扣到 0，差额不发放，不印钱）
-                    const w = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(sellerId);
-                    actualDeduct = Math.min(stakeAmount, Number(w?.balance ?? 0));
-                    if (actualDeduct > 0) {
-                        db.prepare('UPDATE wallets SET balance = balance - ? WHERE user_id = ?').run(actualDeduct, sellerId);
-                    }
-                }
-                // 按 actualDeduct 比例分配（buyer 50% + sys_protocol 50%），保证 入 = 出
-                const compensation = Math.round(actualDeduct * 0.5 * 100) / 100;
-                const protocolShare = Math.round((actualDeduct - compensation) * 100) / 100;
-                if (compensation > 0)
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compensation, buyerId);
-                if (protocolShare > 0)
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(protocolShare, sysUserId);
-            }
+            // 2. 罚没（fault_penalty_rate×total,staked 不足扣自由 balance,绝不印钱）→ RFC-007 守恒分配
+            if (penaltyAmount > 0)
+                forfeitAndDistribute(penaltyAmount);
             // 3. 库存回退（非二手）
             if (!isSecondhand)
                 db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);
@@ -278,27 +365,9 @@ function settleFault(db, orderId, faultState) {
                     if (compToSys > 0)
                         db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compToSys, sysUserId);
                 }
-                // 3. stake 50/50 扣罚（seller 违约：自选 self-fulfill 但没送达）
-                if (stakeAmount > 0) {
-                    let actualDeduct = 0;
-                    if (stakeLocked) {
-                        db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(stakeAmount, sellerId);
-                        actualDeduct = stakeAmount;
-                    }
-                    else {
-                        const w = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(sellerId);
-                        actualDeduct = Math.min(stakeAmount, Number(w?.balance ?? 0));
-                        if (actualDeduct > 0) {
-                            db.prepare('UPDATE wallets SET balance = balance - ? WHERE user_id = ?').run(actualDeduct, sellerId);
-                        }
-                    }
-                    const compensation = Math.round(actualDeduct * 0.5 * 100) / 100;
-                    const protocolShare = Math.round((actualDeduct - compensation) * 100) / 100;
-                    if (compensation > 0)
-                        db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compensation, buyerId);
-                    if (protocolShare > 0)
-                        db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(protocolShare, sysUserId);
-                }
+                // 3. 罚没（self-fulfill seller 违约;fault_penalty_rate×total,staked 不足扣自由 balance）→ RFC-007 守恒分配
+                if (penaltyAmount > 0)
+                    forfeitAndDistribute(penaltyAmount);
                 // 4. 库存回退
                 if (!isSecondhand)
                     db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);
@@ -318,9 +387,10 @@ function settleFault(db, orderId, faultState) {
                 if (bidStakeHeld > 0) {
                     db.prepare('UPDATE wallets SET balance = balance + ?, staked = staked - ? WHERE user_id = ?').run(bidStakeHeld, bidStakeHeld, sellerId);
                 }
-                if (stakeAmount > 0 && stakeLocked) {
+                // seller 无责 → 退还其【该单实际背书的 stake】(= stake_backing;起步阶段=0,无可退)
+                if (orderStakeBacking > 0) {
                     db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                        .run(stakeAmount, stakeAmount, sellerId);
+                        .run(orderStakeBacking, orderStakeBacking, sellerId);
                 }
                 // 3. 库存回退
                 if (!isSecondhand)
@@ -353,6 +423,51 @@ function settleFault(db, orderId, faultState) {
         db.prepare("UPDATE orders SET settled_fault_at = datetime('now') WHERE id = ?").run(orderId);
     })();
 }
+// ─── RFC-007 stage 5：无责拒单结算（仲裁认定客观无责后调用）──────────────────
+//   §无责零成本:买家全额退款 + 卖家质押全退,零罚没、零佣金、零基金入金(无真实成交)。
+//   + 中性 no_fault_decline 信誉事件(points=0,不降分,仅作 rate-observable 信号防滥用)。
+//   守恒:仅做"escrow→买家 balance"和"staked→卖家 balance"两笔内部移动,系统总额不变,绝不印钱。
+export function settleDeclinedNoFault(db, orderId) {
+    db.transaction(() => {
+        const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+        if (!order)
+            return;
+        if (order.settled_fault_at)
+            return; // 幂等(复用 settled_fault_at 标记)
+        const total = Number(order.total_amount);
+        const buyerId = order.buyer_id;
+        const sellerId = order.seller_id;
+        const isSecondhand = order.source === 'secondhand';
+        const orderStakeBacking = Math.max(0, Math.round(Number(order.stake_backing || 0) * 100) / 100);
+        const bidStakeHeld = Number(order.bid_stake_held || 0);
+        // 1. 买家 escrow 全额退回
+        db.prepare('UPDATE wallets SET escrowed = escrowed - ?, balance = balance + ? WHERE user_id = ?').run(total, total, buyerId);
+        // 2. 卖家质押全退(封顶其实际 staked,绝不转负)—— 无责零成本
+        const sellerStaked = Math.max(0, Number(db.prepare('SELECT COALESCE(staked,0) AS s FROM wallets WHERE user_id = ?').get(sellerId)?.s ?? 0));
+        const returnStake = Math.min(orderStakeBacking + bidStakeHeld, sellerStaked);
+        if (returnStake > 0)
+            db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?').run(returnStake, returnStake, sellerId);
+        // 3. 库存 / 二手状态恢复
+        if (!isSecondhand)
+            db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);
+        else {
+            try {
+                db.prepare("UPDATE secondhand_items SET status = 'available', updated_at = datetime('now') WHERE id = ?").run(order.product_id);
+            }
+            catch { }
+        }
+        // 4. 中性 no_fault_decline 信誉事件(points=0 → 不降分;rate-observable 防"假客观"滥用)
+        try {
+            db.prepare('INSERT INTO reputation_events (id, user_id, order_id, event_type, points, reason) VALUES (?,?,?,?,?,?)')
+                .run(generateId('rep'), sellerId, orderId, 'no_fault_decline', 0, `客观无责拒单(仲裁认定) reason=${order.decline_reason_code || ''}`);
+        }
+        catch (e) {
+            console.warn('[no_fault_decline rep event]', e.message);
+        }
+        // 5. 结算标记 + 清临时判责 flag
+        db.prepare("UPDATE orders SET settled_fault_at = datetime('now'), decline_objective_pending = 0 WHERE id = ?").run(orderId);
+    })();
+}
 // ─── 内部工具函数 ─────────────────────────────────────────────
 /** 找出当前订单超时的转移（如果有） */
 function findActiveDeadlineTransition(order, now) {

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

@@ -42,6 +42,29 @@ export function initOrderChainSchema(db) {
     }
     catch { }
 }
+export function listOrderEventsSince(db, userId, since, limit) {
+    const lim = Math.min(200, Math.max(1, Math.floor(limit) || 50));
+    const sinceRid = since && /^\d+$/.test(since) ? Number(since) : 0;
+    const rows = db.prepare(`
+    SELECT e.rowid AS rid, e.order_id, e.seq, e.event_type, e.from_status, e.to_status, e.actor_role,
+           e.event_hash, e.prev_event_hash, e.signed_at, e.created_at
+    FROM order_events e
+    JOIN orders o ON o.id = e.order_id
+    WHERE (o.buyer_id = ? OR o.seller_id = ? OR o.logistics_id = ?)
+      AND e.rowid > ?
+    ORDER BY e.rowid ASC
+    LIMIT ?
+  `).all(userId, userId, userId, sinceRid, lim);
+    const events = rows.map(r => ({
+        cursor: String(r.rid),
+        order_id: r.order_id, seq: r.seq, event_type: r.event_type,
+        from_status: r.from_status, to_status: r.to_status, actor_role: r.actor_role,
+        event_hash: r.event_hash, prev_event_hash: r.prev_event_hash, signed_at: r.signed_at, created_at: r.created_at,
+    }));
+    const has_more = events.length === lim;
+    const next_cursor = events.length ? events[events.length - 1].cursor : (since ?? null);
+    return { events, next_cursor, has_more };
+}
 // canonical_payload — 递归 stringify，每层 key 字母序
 // 修复 ultrareview bug_012：浅排序让嵌套对象用插入序，破坏"独立验证"承诺
 // （已知问题：arbitration_ruling 时 liability_parties 是嵌套数组）

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

@@ -177,9 +177,12 @@ export const VALID_TRANSITIONS = {
         description: '买家超时未付款，自动取消并标记违约'
     },
     'paid→fault_seller': {
-        allowedRoles: ['system'],
+        // RFC-007 stage 2：除 system 超时判责外,允许 seller 【主动拒单】(decline) 显式触发此转移。
+        //   主动拒单 = 卖家明确不接此单(vs 沉默超时),记 decline_reason_code + declined_at。
+        //   stage 2 一律走违约路径(与超时同结算);stage 3 auto-verify 上线后,客观无责拒单将改判 declined_nofault。
+        allowedRoles: ['system', 'seller'],
         requiresEvidence: false,
-        description: '卖家超时未接单，自动退款并标记违约'
+        description: '卖家未接单：system 超时判责 或 seller 主动拒单(decline),退款买家并按违约结算'
     },
     'accepted→fault_seller': {
         allowedRoles: ['system'],
@@ -201,6 +204,18 @@ export const VALID_TRANSITIONS = {
         requiresEvidence: false,
         description: '物流超时未投递，标记物流违约'
     },
+    // ── RFC-007 stage 5：客观拒单仲裁翻案 ─────────────────────────────
+    //   临时判责(fault_seller + decline_objective_pending)经【人工仲裁】认定客观无责 → declined_nofault。
+    'fault_seller→declined_nofault': {
+        allowedRoles: ['arbitrator', 'system'],
+        requiresEvidence: false,
+        description: 'RFC-007：客观拒单经人工仲裁认定无责 → 翻案为无责拒单(全退买家+退卖家质押,零罚没)'
+    },
+    'declined_nofault→completed': {
+        allowedRoles: ['system'],
+        requiresEvidence: false,
+        description: 'RFC-007：无责拒单结算完成(买家全额退款,卖家质押全退,无罚没无佣金)'
+    },
     // ── 判责后的处置结算 ─────────────────────────────────────────
     'fault_seller→completed': {
         allowedRoles: ['system'],
@@ -236,3 +251,51 @@ export const CURRENT_RESPONSIBLE_SELF_FULFILL = {
     picked_up: 'seller',
     in_transit: 'seller',
 };
+// ─── RFC-011 §① 实体语义:订单状态机契约(doc=code,从 VALID_TRANSITIONS 生成)───────────
+// 状态【含义】是 authored(枚举注释无法运行时取);转移由 VALID_TRANSITIONS 生成(零漂移)。
+// 覆盖锁:tests/test-order-lifecycle-contract.ts 断言每个 OrderStatus 有含义 + 每条转移被序列化。
+export const ORDER_STATE_MEANINGS = {
+    created: { zh: '已下单,等待买家付款', en: 'placed, awaiting buyer payment' },
+    paid: { zh: '资金已托管(escrow),等待卖家接单', en: 'funds in escrow, awaiting seller acceptance' },
+    accepted: { zh: '卖家已接单,承诺履约', en: 'seller accepted, committed to fulfil' },
+    shipped: { zh: '卖家已交物流/自履行发出', en: 'handed to logistics / self-fulfil dispatched' },
+    picked_up: { zh: '物流已揽收', en: 'picked up by logistics' },
+    in_transit: { zh: '运输中', en: 'in transit' },
+    delivered: { zh: '已投递,等待买家确认', en: 'delivered, awaiting buyer confirmation' },
+    confirmed: { zh: '买家确认收货 → 触发结算', en: 'buyer confirmed → triggers settlement' },
+    disputed: { zh: '争议中,等待人工仲裁', en: 'in dispute, awaiting human arbitration' },
+    completed: { zh: '交易完成,资金已分配(终态)', en: 'completed, funds settled (terminal)' },
+    cancelled: { zh: '已取消(终态)', en: 'cancelled (terminal)' },
+    fault_buyer: { zh: '买家违约(超时未付,终态)', en: 'buyer fault (payment timeout, terminal)' },
+    fault_seller: { zh: '卖家违约(超时未接/发 或 主动拒单)', en: 'seller fault (accept/ship timeout or active decline)' },
+    fault_logistics: { zh: '物流违约', en: 'logistics fault' },
+    declined_nofault: { zh: '卖家无责拒单(仲裁认定客观)→ 全退买家+退卖家质押,零罚没(终态)', en: 'seller no-fault decline (arbitration-cleared) → full refund + stake returned, no forfeit (terminal)' },
+    resolved_for_seller: { zh: '仲裁裁卖家胜诉,资金释放(终态)', en: 'arbitration ruled for seller, funds released (terminal)' },
+    refunded_partial: { zh: '仲裁裁部分退款(终态)', en: 'arbitration partial refund (terminal)' },
+    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)' },
+};
+/** 订单/争议生命周期契约 —— 集成方 agent 读它即懂"订单怎么流转 + 每步谁驱动 + 何时 + 含义"。 */
+export function orderLifecycleContract() {
+    const keys = Object.keys(VALID_TRANSITIONS);
+    const states = Object.keys(ORDER_STATE_MEANINGS).map(s => ({
+        state: s, zh: ORDER_STATE_MEANINGS[s].zh, en: ORDER_STATE_MEANINGS[s].en,
+        responsible: CURRENT_RESPONSIBLE[s] ?? null,
+        terminal: !keys.some(k => k.startsWith(s + '→')), // 无出边 = 终态
+    }));
+    const transitions = Object.entries(VALID_TRANSITIONS).map(([key, t]) => {
+        const arrow = key.indexOf('→');
+        return {
+            from: key.slice(0, arrow), to: key.slice(arrow + 1),
+            allowed_roles: t.allowedRoles, deadline_field: t.deadlineField ?? null,
+            requires_evidence: !!t.requiresEvidence, auto_fault_state: t.autoFaultState ?? null,
+            description: t.description,
+        };
+    });
+    return {
+        entity: 'order',
+        note: 'Order/dispute lifecycle, generated from the protocol state machine (VALID_TRANSITIONS) — doc=code. State changes are observable via the event stream (§⑥ GET /api/agent/events) and integrity-verifiable via the signed chain (§⑤ GET /api/orders/:id/chain).',
+        states, transitions,
+    };
+}

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

@@ -30,7 +30,9 @@ import { initReputationSchema, recordOrderReputation, getReputation, getSearchBo
 import { generateManifest, getManifestSummary, MANIFEST_URI, } from '../../layer0-foundation/L0-5-manifest/manifest.js';
 import { requireAuth } from './auth.js';
 import { createHash, randomBytes } from 'node:crypto';
-const SERVER_VERSION = '0.1.8';
+import { SOFTWARE_VERSION } from '../../version.js';
+// RFC-011 §④:版本单一来源 = package.json(经 src/version.ts)。不再硬编码(旧 '0.1.8' 早漂移到 0.1.19)。
+const SERVER_VERSION = SOFTWARE_VERSION;
 const TELEMETRY_URL = process.env.WEBAZ_TELEMETRY_URL ?? 'https://webaz.xyz/api/mcp-telemetry';
 // 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.
@@ -239,7 +241,7 @@ const TOOLS = [
     {
         name: 'webaz_info',
         description: `Get WebAZ documentation and usage guide. Call this FIRST when onboarding a new agent.
-Returns: protocol overview, available tools, role responsibilities, operation flows, **network_state (pre-launch disclaimer)**, **commission_model.compliance_notice (MLM-form disclosure)**.
+Returns: protocol overview, available tools, role responsibilities, operation flows, **network_state (pre-launch disclaimer)**, **commission_model (3-tier share, jurisdiction-graded, explicit attribution, opt-in)**.
 No auth required, no parameters needed.
 
 ⚠️ Important: WebAZ is currently **pre-launch** with ~0 real users on the canonical endpoint. All stats / counts returned by this and other tools come from the **local MCP SQLite DB**, not protocol-wide prod state. Read network_state field BEFORE you treat any number as real-economy data.`,
@@ -253,7 +255,7 @@ No auth required, no parameters needed.
         // was ~1732 chars, now ~780 chars
         description: `Register a new WebAZ account. Returns: api_key (36-char 128-bit credential, store securely) + permanent_code (6-char recovery code, pair with handle in webaz_mykey to recover lost api_key) + handle (URL-safe ID; if taken, system appends numeric suffix — check handle_modified flag) + created_at.
 
-⚠️ **Consent required (MLM disclosure)**: WebAZ is pre-launch with 3-tier commission + binary PV pairing structure (may overlap with MLM legal definitions; see webaz_info.commission_model.compliance_notice). Agent acting on behalf of human user **MUST get explicit informed consent BEFORE creating account**. Do NOT auto-register from generic shopping questions.
+⚠️ **Consent required**: creating an account on a human user's behalf registers an economic-relationship account (can participate in commission). Agent acting for a human user **MUST get explicit informed consent BEFORE creating account**. Do NOT auto-register from generic shopping questions.
 
 Roles: buyer (browse/order/confirm) | seller (list/accept/ship) | logistics (pickup/transit/deliver) | reviewer (reviews) | arbitrator (disputes/rulings).
 
@@ -478,10 +480,15 @@ Missing deadline → protocol auto-marks party in default.`,
                 order_id: { type: 'string', description: 'Order ID' },
                 action: {
                     type: 'string',
-                    enum: ['accept', 'ship', 'pickup', 'transit', 'deliver', 'confirm', 'dispute'],
-                    description: 'Action to execute',
+                    enum: ['accept', 'ship', 'pickup', 'transit', 'deliver', 'confirm', 'dispute', 'decline', 'contest_decline'],
+                    description: 'Action to execute. decline = seller actively refuses a paid order (vs silent timeout); requires decline_reason_code. contest_decline = seller opens human arbitration on an objective-claimed provisional fault (within the contest window) to be cleared to no-fault; pass evidence_description.',
                 },
                 notes: { type: 'string', description: 'Action note (e.g. tracking number, dispute reason)' },
+                decline_reason_code: {
+                    type: 'string',
+                    enum: ['stock_consumed_concurrent', 'stale_price_snapshot', 'force_majeure', 'price_regret', 'cherry_pick', 'other'],
+                    description: 'Required for action=decline. Why the seller refuses. Subjective (price_regret / cherry_pick / other) → settles immediately as seller-fault (buyer fully refunded). Objective-claimed (stock_consumed_concurrent / stale_price_snapshot / force_majeure) → PROVISIONAL fault: not settled yet, opens a contest window — seller must open arbitration (webaz_dispute) with evidence to be cleared (these off-chain facts have no on-protocol auto-verification); uncontested by the deadline → auto-finalizes as fault.',
+                },
                 evidence_description: {
                     type: 'string',
                     description: 'Evidence description (recommended for ship/pickup/deliver; required for dispute)',
@@ -795,7 +802,7 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
 
 ⚠️ **Opt-in required (RFC-002)**: rewards default = off. \`rewards_status\` field returns 4-state {opted_in | never_activated | auto_downgraded | deactivated} + pending_escrow tally. Opted-out users still see attribution + tree, but commission held in escrow until activation via PWA #me.
 
-⚠️ **MLM disclosure**: structure may overlap with MLM legal definitions (see webaz_info.commission_model.compliance_notice). Agent acting for human user **MUST get explicit consent** before generating referral links / promoting. Do NOT auto-recruit.`,
+⚠️ **Consent required**: generating referral links / promoting on a human user's behalf needs the user's explicit authorization. Agent **MUST get explicit consent** before generating referral links / promoting. Do NOT auto-recruit.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -810,7 +817,7 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
 
 ⚠️ **Opt-in required (RFC-002 §3.5)**: this is a valuation-layer action. Caller must have \`rewards_opted_in=1\` (builder-identity opt-in). Opted-out users get \`{error: 'rewards_opt_in_required', missing_requirements, next_steps}\` — direct user to PWA #me to apply.
 
-⚠️ **MLM disclosure**: builds referral chain (multi-tier commission + binary pairing). Agent acting for human user **MUST get explicit consent**. Do NOT auto-generate. See webaz_info.commission_model.compliance_notice.`,
+⚠️ **Consent required**: this builds a referral chain on the user's behalf. Agent acting for a human user **MUST get explicit consent**. Do NOT auto-generate. See webaz_info.commission_model.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1359,7 +1366,7 @@ Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyon
 
 Actions:
 - list_open (default): open tasks (opt. area filter)
-- claim: take an open task; provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted
+- claim: take an open task; provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a **handoff** (repo + AGENTS.md + PR flow) — point a coding agent at it to actually do the work; the human needn't know git.
 - submit: mark in_review with pr_ref
 - status: tasks you hold (claimed/in_review)
 - profile: your build dashboard — KPI/tier/restrictions+appeal, self-view (private, no public leaderboard)
@@ -1439,9 +1446,22 @@ async function handleContribute(args) {
         const tid = args.task_id;
         if (!tid)
             return { error: 'task_id required for action=claim' };
-        return apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/claim', {
+        const r = await apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/claim', {
             method: 'POST', apiKey, body: { provenance: args.provenance },
         });
+        // RFC-006 断点1(b)交接:认领成功后直接下发"怎么真正动手",让贡献者的【编码 agent】接手 git/PR。
+        //   关键:人不必会 git——人的编码 agent(如 Claude Code)做;人(Passkey 真人)担责。
+        if (!r.error) {
+            r.handoff = {
+                repo: 'https://github.com/seasonsagents-art/webaz',
+                start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
+                do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo; work on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
+                pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, add 🤖🤖🤖 to the PR title + a meta-rule trace. Humans merge — no auto-merge.',
+                then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${tid} pr_ref=#<N>.`,
+                human_note: "You don't need to know git — your coding agent does it; you (the Passkey-bound human) stay accountable.",
+            };
+        }
+        return r;
     }
     if (action === 'submit') {
         const tid = args.task_id;
@@ -1492,8 +1512,9 @@ function handleInfo() {
     return {
         ...summary,
         // 诚实化披露 — 排在 stats / quick_start 之前,让 agent 先建立正确预期。
-        // 第三方尽调 agent 抓到过的破绽:live_stats 是本地库数字、引导词推 agent 拉新、佣金结构有 MLM 形态。
-        // 此处主动披露,不抗辩;agent 自己判断如何处理。
+        // 第三方尽调 agent 抓到过的破绽:live_stats 是本地库数字、引导词推 agent 拉新。
+        // 此处主动披露真实状态(pre-launch / 数据来源),不抗辩;agent 自己判断如何处理。
+        // 佣金按【功能】中性描述(commission_model),不做"自证不是X"的辩护——正常机制无需自证。
         network_state: {
             // RFC-003 P3：显式声明当前客户端模式，让 agent 一眼分清"真网络 vs 本机沙盒"
             mode: MODE, // 'network' | 'sandbox'
@@ -1517,15 +1538,15 @@ function handleInfo() {
         },
         live_stats: stats,
         economics,
-        // QA 轮 14.c P1：显式归因机制（与传统 MLM 自动吃下线的根本区别）
+        // 佣金机制 —— 纯功能性描述(怎么运作),不做"自证清白"式辩护。
         commission_model: {
-            split: '7:2:1 — L1 70% / L2 20% / L3 10% of commission_pool',
-            attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, NOT auto-derived from the buyer\'s sponsor chain. 防 MLM 寡头化（上线不会自动吃下线每一单）。',
-            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records direct promoter. Full L2/L3 chain requires buyer to arrive via webaz_share_link ?ref= URL clicked in browser (builds product_share_attribution).',
-            redirect_rules: 'chain_gap (无 L / sponsor 无效) → charity_fund; region cap (level > region max_levels) → global_fund. global region max_levels=1 (仅 L1)；singapore 等 max_levels=3.',
-            l1_gate: 'promoter 必须是 verified buyer（≥1 笔完成订单）才能领 commission，否则该份 redirect。',
-            // 主动披露,不要让外部尽调 agent 自己读出来再写差评
-            compliance_notice: '⚠️ 本协议含三级佣金(L1/L2/L3 7:2:1) + 二元配对树(binary PV matching) + 邀请链结构。这类形态在多数司法辖区可能与**多层级营销(MLM)的法律定义重叠**。本协议通过显式 per-order 归因(非自动吃下线)规避了 MLM 寡头化的核心病灶,但形态层面仍带 MLM 特征,我们诚实告知。**代理 AI 不应默认替终端用户生成推广链接或拉新**——这需要用户的显式授权,且用户自身要先评估当地合规性。\n\n**Reward participation is opt-in (RFC-002)**: default = off. Users must apply (Passkey + ≥1 completed order); attribution always recorded (relation layer), but commission settlement gated until opt-in. Pending commission held in pending_commission_escrow for 30d grace. See docs/rfcs/RFC-002-rewards-opt-in.md for full state matrix.',
+            split: '7:2:1 — L1 70% / L2 20% / L3 10% of an order\'s commission_pool',
+            jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → community fund).',
+            attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, not derived from the buyer\'s sponsor chain.',
+            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link ?ref= URL clicked in a browser (builds product_share_attribution).',
+            redirect_rules: 'chain_gap (no L / invalid sponsor) → charity_fund; level beyond the region cap → global_fund.',
+            l1_gate: 'the promoter must be a verified buyer (≥1 completed order) to receive commission, otherwise that share redirects.',
+            opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded, but commission settlement is gated until opt-in (pending held in pending_commission_escrow, 30d grace). See docs/rfcs/RFC-002-rewards-opt-in.md.',
         },
         // QA 轮 3 FAIL：roles 漏 reviewer。register 工具支持 5 个角色，info 必须列全。
         roles: {
@@ -2328,6 +2349,7 @@ async function handleUpdateOrder(args) {
                 action,
                 notes: args.notes ?? '',
                 evidence_description: args.evidence_description ?? '',
+                ...(args.decline_reason_code ? { decline_reason_code: args.decline_reason_code } : {}),
                 ...(args.logistics_company_id ? { logistics_company_id: args.logistics_company_id } : {}),
             },
         });
@@ -4215,7 +4237,9 @@ function settleOrder(db, orderId) {
 }
 // ─── MCP Server 主体 ──────────────────────────────────────────
 export async function startMCPServer() {
-    const server = new Server({ name: 'dcp-protocol', version: '0.1.0' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+    const server = new Server(
+    // name 是客户端配置引用的 server 标识(勿改);version 走单一来源(旧硬编码 '0.1.0' 已漂移)。
+    { name: 'dcp-protocol', version: SOFTWARE_VERSION }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     // ── MCP Resources：协议 Manifest ─────────────────────────────
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
@@ -4264,7 +4288,7 @@ export async function startMCPServer() {
         },
         {
             name: 'webaz-onboard',
-            description: 'Onboarding for a new agent first connecting to webaz — explains protocol nature / pre-launch state / MLM shape / registration path / user-authorization boundaries. Read webaz_info first, then run this prompt.',
+            description: 'Onboarding for a new agent first connecting to webaz — explains protocol nature / pre-launch state / commission model / registration path / user-authorization boundaries. Read webaz_info first, then run this prompt.',
             arguments: [],
         },
         {
@@ -4325,7 +4349,7 @@ export async function startMCPServer() {
                         type: 'text',
                         text: `请先调用 webaz_info 拿到完整协议状态,然后跟我确认以下几点理解:\n\n` +
                             `1. **网络阶段(network_state.phase)**:webaz 目前是什么状态?真实用户数多少?\n` +
-                            `2. **经济模型(commission_model.compliance_notice)**:协议含三级佣金 + 二元 PV 配对结构 — 在多数辖区可能与 MLM 法律定义重叠。` +
+                            `2. **经济模型(commission_model)**:三级佣金 7:2:1,按辖区 max_levels 分级(非各地无差别三级),显式 per-order 归因,opt-in 结算(默认 off)。` +
                             `代理 AI 不应默认替终端用户生成推广链接或拉新,需用户显式授权。\n` +
                             `3. **数据来源**:工具返回的所有 stats 是本机 MCP 数据库的本地计数,不代表协议全网真实状态。\n` +
                             `4. **铁律(Iron Rule)**:vote / arbitrate / agent_revoke / delete_passkey / 大额提现需要用户在 PWA 完成 WebAuthn ceremony,` +