@seasonkoh/webaz 0.1.21 → 0.1.22

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

@@ -12,6 +12,21 @@
 import { generateId } from '../L0-1-database/schema.js';
 import { appendOrderEvent } from './order-chain.js';
 import { VALID_TRANSITIONS, CURRENT_RESPONSIBLE, CURRENT_RESPONSIBLE_SELF_FULFILL } from './transitions.js';
+// RFC-014 PR2 — 资金算术统一走整数 base-units;分配用 allocate 保证精确守恒。
+import { toUnits, toDecimal, mulRate, allocate } from '../../money.js';
+// RFC-014 PR3 — 钱包落库 helper 抽到共享 ledger 模块(原私有于此),防多份漂移。
+import { walletUnits, applyWalletDelta } from '../../ledger.js';
+// ─── RFC-014 公池入金 helper ───────────────────────────────────
+function creditReserveUnits(db, fromUserId, amountUnits, orderId, note) {
+    if (amountUnits <= 0)
+        return;
+    const cur = db.prepare("SELECT COALESCE(balance,0) balance, COALESCE(total_orphan_sponsor,0) tos FROM commission_reserve WHERE id='main'").get();
+    const newBal = toDecimal(toUnits(cur?.balance ?? 0) + amountUnits);
+    const newTos = toDecimal(toUnits(cur?.tos ?? 0) + amountUnits);
+    db.prepare(`UPDATE commission_reserve SET balance = ?, total_orphan_sponsor = ?, updated_at = datetime('now') WHERE id = 'main'`).run(newBal, newTos);
+    db.prepare(`INSERT INTO commission_reserve_txns (id, kind, from_user_id, amount, related_order_id, note) VALUES (?,?,?,?,?,?)`)
+        .run(generateId('crt'), 'redirect_orphan_sponsor', fromUserId, toDecimal(amountUnits), orderId, note);
+}
 // ─── 核心函数 ────────────────────────────────────────────────
 /**
  * 执行状态转移
@@ -236,8 +251,10 @@ export function settleFault(db, orderId, faultState) {
             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-014:金额一律转整数 base-units 后再算/分配。
+        const totalU = toUnits(total);
+        const penaltyU = isSecondhand ? 0 : mulRate(totalU, faultPenaltyRate());
+        const orderStakeBackingU = Math.max(0, toUnits(Number(order.stake_backing || 0)));
         // RFC-007 stage 4：没收后的【守恒 + 不牟利】再分配(取代旧的 buyer 50% / protocol 50%)。
         //   旧分配漏掉推广人(违反 §谁责任谁承担:推广人承担了真实推广成本却零补偿)。
         //   新规则(全部用订单快照,可复算,绝不印钱):
@@ -248,92 +265,81 @@ export function settleFault(db, orderId, faultState) {
         //     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 表示起步免赔付,无没收无印钱)
+        // 罚没【收取 + RFC-007 守恒分配】(整数 base-units;allocate 保证精确守恒),返回实扣额 units(0=起步免赔付)
         const forfeitAndDistribute = (penalty) => {
             // 起步免赔付:无背书订单(stake_backing=0)绝不没收、绝不碰新商家自由余额
-            if (orderStakeBacking <= 0)
+            if (orderStakeBackingU <= 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);
+            // 收取:先扣 staked(封顶背书额),不足再扣卖家自由 balance(责任自负;封顶其真实余额→不转负)
+            const fromStaked = Math.min(penalty, orderStakeBackingU);
+            const remainder = penalty - fromStaked;
+            const sellerBalU = Math.max(0, walletUnits(db, sellerId).balance);
+            const fromBalance = Math.min(remainder, sellerBalU);
+            const F = 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);
+            applyWalletDelta(db, sellerId, { staked: -fromStaked, balance: -fromBalance });
             // 1. 协议回收原始平台费(封顶 F,不牟利)
-            const protocolTake = round2(Math.min(F, total * protocolFeeRate()));
+            const protocolTake = Math.min(F, mulRate(totalU, 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);
+                applyWalletDelta(db, sysUserId, { balance: protocolTake });
+            // 2. R 与买家补偿(精确平分:allocate 两桶求和 ≡ R)
+            const R = F - protocolTake;
+            const [buyerComp, promoterHalf] = allocate(R, [1, 1]);
             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);
+                applyWalletDelta(db, buyerId, { balance: buyerComp });
+            // 3. 推广半 → l1/l2/l3 按原始佣金比例分,封顶原始佣金总额(allocate 求和 ≡ payable)
             const commissionRate = Number(order.snapshot_commission_rate ?? 0);
-            const pool = round2(total * (Number.isFinite(commissionRate) && commissionRate > 0 ? commissionRate : 0));
+            const poolU = mulRate(totalU, 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]) },
+                { uid: order.l1_uid, orig: mulRate(poolU, FORFEIT_LEVEL_RATES[1]) },
+                { uid: order.l2_uid, orig: mulRate(poolU, FORFEIT_LEVEL_RATES[2]) },
+                { uid: order.l3_uid, orig: mulRate(poolU, FORFEIT_LEVEL_RATES[3]) },
             ].filter(l => l.uid); // 仅【真实存在的推广人】参与
-            const originalCommissionTotal = round2(levels.reduce((s, l) => s + l.orig, 0));
+            const originalCommissionTotal = 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));
+                const shares = allocate(payable, levels.map(l => l.orig));
+                levels.forEach((l, i) => {
+                    const share = shares[i];
                     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);
-                }
+                        return;
+                    applyWalletDelta(db, l.uid, { balance: share, earned: share });
+                    promotersPaid += share;
+                });
             }
             // 4. 推广半残值(超封顶 / 无推广人 / 取整余数)→ 三级公池;绝不给买家、绝不印钱
-            reserveResidual(promoterHalf - promotersPaid, `RFC-007 fault forfeit residual order=${orderId}`);
+            creditReserveUnits(db, sellerId, promoterHalf - promotersPaid, orderId, `RFC-007 fault forfeit residual order=${orderId}`);
             return F;
         };
         // P0.1：RFQ 路径的 bid_stake_held — fault 时由各分支按规则处理
-        const bidStakeHeld = Number(order.bid_stake_held || 0);
+        const bidStakeHeldU = toUnits(Number(order.bid_stake_held || 0));
+        // bid_stake_held 没收 50/50 的公用逻辑(中标后弃单的额外惩罚)
+        const forfeitBidStake5050 = () => {
+            if (bidStakeHeldU <= 0)
+                return;
+            applyWalletDelta(db, sellerId, { staked: -bidStakeHeldU });
+            const [compBuyer, compSys] = allocate(bidStakeHeldU, [1, 1]);
+            if (compBuyer > 0)
+                applyWalletDelta(db, buyerId, { balance: compBuyer });
+            if (compSys > 0)
+                applyWalletDelta(db, sysUserId, { balance: compSys });
+        };
         if (faultState === 'fault_seller') {
             // 1. buyer escrow 全额退回
-            db.prepare('UPDATE wallets SET escrowed = escrowed - ?, balance = balance + ? WHERE user_id = ?')
-                .run(total, total, buyerId);
+            applyWalletDelta(db, buyerId, { escrowed: -totalU, balance: totalU });
             // P0.1：bid_stake_held 没收 50/50（中标后弃单的额外惩罚）
-            if (bidStakeHeld > 0) {
-                db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(bidStakeHeld, sellerId);
-                const compToBuyer = Math.round(bidStakeHeld * 0.5 * 100) / 100;
-                const compToSys = Math.round((bidStakeHeld - compToBuyer) * 100) / 100;
-                if (compToBuyer > 0)
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compToBuyer, buyerId);
-                if (compToSys > 0)
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compToSys, sysUserId);
-            }
+            forfeitBidStake5050();
             // 2. 罚没（fault_penalty_rate×total,staked 不足扣自由 balance,绝不印钱）→ RFC-007 守恒分配
-            if (penaltyAmount > 0)
-                forfeitAndDistribute(penaltyAmount);
+            if (penaltyU > 0)
+                forfeitAndDistribute(penaltyU);
             // 3. 库存回退（非二手）
             if (!isSecondhand)
                 db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);
@@ -353,21 +359,12 @@ export function settleFault(db, orderId, faultState) {
             const isSelfFulfill = !order.logistics_id;
             if (isSelfFulfill) {
                 // 1. buyer escrow 全额退回
-                db.prepare('UPDATE wallets SET escrowed = escrowed - ?, balance = balance + ? WHERE user_id = ?')
-                    .run(total, total, buyerId);
+                applyWalletDelta(db, buyerId, { escrowed: -totalU, balance: totalU });
                 // 2. bid_stake_held 没收 50/50（同 fault_seller 逻辑）
-                if (bidStakeHeld > 0) {
-                    db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(bidStakeHeld, sellerId);
-                    const compToBuyer = Math.round(bidStakeHeld * 0.5 * 100) / 100;
-                    const compToSys = Math.round((bidStakeHeld - compToBuyer) * 100) / 100;
-                    if (compToBuyer > 0)
-                        db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compToBuyer, buyerId);
-                    if (compToSys > 0)
-                        db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(compToSys, sysUserId);
-                }
+                forfeitBidStake5050();
                 // 3. 罚没（self-fulfill seller 违约;fault_penalty_rate×total,staked 不足扣自由 balance）→ RFC-007 守恒分配
-                if (penaltyAmount > 0)
-                    forfeitAndDistribute(penaltyAmount);
+                if (penaltyU > 0)
+                    forfeitAndDistribute(penaltyU);
                 // 4. 库存回退
                 if (!isSecondhand)
                     db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);
@@ -381,17 +378,13 @@ export function settleFault(db, orderId, faultState) {
             else {
                 // Phase 2 logistics 市场：真正的 logistics 接单后违约
                 // 1. buyer escrow 全额退回
-                db.prepare('UPDATE wallets SET escrowed = escrowed - ?, balance = balance + ? WHERE user_id = ?')
-                    .run(total, total, buyerId);
+                applyWalletDelta(db, buyerId, { escrowed: -totalU, balance: totalU });
                 // 2. seller 无责 → bid_stake_held / stake 全额返还
-                if (bidStakeHeld > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ?, staked = staked - ? WHERE user_id = ?').run(bidStakeHeld, bidStakeHeld, sellerId);
-                }
+                if (bidStakeHeldU > 0)
+                    applyWalletDelta(db, sellerId, { balance: bidStakeHeldU, staked: -bidStakeHeldU });
                 // seller 无责 → 退还其【该单实际背书的 stake】(= stake_backing;起步阶段=0,无可退)
-                if (orderStakeBacking > 0) {
-                    db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                        .run(orderStakeBacking, orderStakeBacking, sellerId);
-                }
+                if (orderStakeBackingU > 0)
+                    applyWalletDelta(db, sellerId, { staked: -orderStakeBackingU, balance: orderStakeBackingU });
                 // 3. 库存回退
                 if (!isSecondhand)
                     db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);
@@ -415,9 +408,8 @@ export function settleFault(db, orderId, faultState) {
                 catch { }
             }
             // P0.1：买家违约 → bid_stake_held 全额返还卖家（卖家未失责）
-            if (bidStakeHeld > 0) {
-                db.prepare('UPDATE wallets SET balance = balance + ?, staked = staked - ? WHERE user_id = ?').run(bidStakeHeld, bidStakeHeld, sellerId);
-            }
+            if (bidStakeHeldU > 0)
+                applyWalletDelta(db, sellerId, { balance: bidStakeHeldU, staked: -bidStakeHeldU });
         }
         // 标记已结算（防止重复处置）
         db.prepare("UPDATE orders SET settled_fault_at = datetime('now') WHERE id = ?").run(orderId);
@@ -434,19 +426,20 @@ export function settleDeclinedNoFault(db, orderId) {
             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);
+        // RFC-014:整数 base-units
+        const totalU = toUnits(Number(order.total_amount));
+        const orderStakeBackingU = Math.max(0, toUnits(Number(order.stake_backing || 0)));
+        const bidStakeHeldU = toUnits(Number(order.bid_stake_held || 0));
         // 1. 买家 escrow 全额退回
-        db.prepare('UPDATE wallets SET escrowed = escrowed - ?, balance = balance + ? WHERE user_id = ?').run(total, total, buyerId);
+        applyWalletDelta(db, buyerId, { escrowed: -totalU, balance: totalU });
         // 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);
+        const sellerStakedU = Math.max(0, walletUnits(db, sellerId).staked);
+        const returnStake = Math.min(orderStakeBackingU + bidStakeHeldU, sellerStakedU);
         if (returnStake > 0)
-            db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?').run(returnStake, returnStake, sellerId);
+            applyWalletDelta(db, sellerId, { staked: -returnStake, balance: returnStake });
         // 3. 库存 / 二手状态恢复
         if (!isSecondhand)
             db.prepare('UPDATE products SET stock = stock + 1 WHERE id = ?').run(order.product_id);

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

@@ -1529,6 +1529,19 @@ function handleInfo() {
             disclaimer: '本协议尚未公开上线,prod 真实用户≈0,无真实经济流转。下方 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。
+        for_end_user: {
+            note: 'What WebAZ does FOR a buyer (why use it): / 这个协议对买家有什么用(为什么用它):',
+            value: [
+                'Escrow on every order — your money is held by the protocol and only released to the seller after you confirm receipt (or an auto-confirm window). / 每笔订单托管:钱由协议托管,你确认收货(或到自动确认期)才放款给卖家。',
+                'Automatic fault ruling — if the seller does not accept / ship / deliver in time, the protocol auto-refunds you, no haggling. / 自动判责:卖家不接单/不发货/不送达超时,协议自动退款给你,无需扯皮。',
+                'Disputes with evidence + arbitration — open a dispute with proof; a neutral process decides. / 争议可凭证据发起 + 中立仲裁裁决。',
+                'Decision-ready transparency — price history, seller reputation, win/loss record and arbitration precedents are public before you buy. / 知情决策:价格历史、卖家信誉、胜诉/败诉记录、仲裁判例,下单前都公开可查。',
+                'Agent-native — your AI agent can compare prices, place orders, and track fulfillment for you via the MCP tools. / agent 原生:你的 AI 可经 MCP 工具替你比价、下单、跟踪履约。',
+            ],
+            honesty: 'Pre-launch: WAZ is a simulated test currency, no real money settles yet. Don\'t treat balances as real value. / 尚未上线:WAZ 是模拟测试币,暂无真实资金结算,余额勿当真实价值。',
+            try_it: 'Browse without an account at https://webaz.xyz/#discover ; the protocol state is public at https://webaz.xyz/.well-known/webaz-protocol.json',
+        },
         // 连接两个场景:用协议(本工具) ↔ 改协议(开发协作)。想改 WebAZ 本身的 agent 从这里进。
         for_contributors: {
             note: 'Want to change WebAZ itself (not just use it)? This is an open, agent-native protocol — AI-authored PRs are welcome, with accountability. / 想改 WebAZ 本身(不只是用)?这是开放的 agent 原生协议,欢迎 AI 提 PR,但需问责。',