@seasonkoh/webaz 0.1.21 → 0.1.23

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

@@ -12,6 +12,10 @@
 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, mulRate, allocate } from '../../money.js';
+// RFC-014 PR3 — 钱包落库 helper 抽到共享 ledger 模块(原私有于此),防多份漂移。
+import { walletUnits, applyWalletDelta } from '../../ledger.js';
 // ─── 核心函数 ────────────────────────────────────────────────
 /**
  * 执行状态转移
@@ -236,104 +240,101 @@ 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%)。
         //   旧分配漏掉推广人(违反 §谁责任谁承担:推广人承担了真实推广成本却零补偿)。
         //   新规则(全部用订单快照,可复算,绝不印钱):
         //     1. 协议只回收【原本该收的平台费】protocolTake = min(F, total × protocol_fee_rate)
         //        —— 协议不从违约牟利;fund_base(1%) 排除(无成交=无 GMV,社区基金不应从罚没获利)。
-        //     2. R = F − protocolTake;买家补偿 = R × 50%(受损对手方固定份额)。
+        //     2. R = F − protocolTake;买家补偿 = R × 50% 起(受损对手方基础份额)。
         //     3. 推广人 = R 的另一半,按 l1/l2/l3 原始佣金比例分,【封顶各自原始佣金】—— 永不超过其真实损失。
-        //     4. 推广半残值(超封顶 / 无推广人)→ commission_reserve 三级公池(与正常单未归属佣金同去向,不给买家=不过补)。
+        //     4. 推广半残值(超封顶 / 无推广人)→ 【买家】(受损方吸收违约方罚金剩余,故买家可超 50%)。
+        //        决策 A(2026-06-07,对齐 RFC-007 Invariant #2):残值是罚金且无成交,归被坑方,不入 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}`);
+            // 4. 推广半残值(超封顶 / 无推广人 / 取整余数)→ 【买家】(受损方吸收违约方罚金剩余,可超 50%)。
+            //    决策 A(2026-06-07):对齐 RFC-007 Invariant #2「buyer absorbs the residual」+ 公开 economic.json。
+            //    理由:残值是【卖家罚金 + 无成交】,非正常单的未归属销售 margin,故归被坑的对手方,不入 commission_reserve。
+            //    守恒:protocolTake + (buyerComp+residual) + promotersPaid = protocolTake + R = F。绝不印钱。
+            const residual = promoterHalf - promotersPaid;
+            if (residual > 0)
+                applyWalletDelta(db, buyerId, { balance: residual });
             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 +354,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 +373,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 +403,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 +421,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);