@seasonkoh/webaz 0.1.20 → 0.1.22

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

@@ -14,6 +14,9 @@
  */
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
 import { transition } from '../../layer0-foundation/L0-2-state-machine/engine.js';
+// RFC-014 PR5 — 争议资金处置走整数 base-units + 绝对值落库 + allocate 精确拆分。
+import { toUnits, toDecimal, mulRate, allocate } from '../../money.js';
+import { applyWalletDelta, debitStakeThenBalance } from '../../ledger.js';
 // ─── Schema 初始化（幂等，安全重复调用）────────────────────────
 /**
  * 为 disputes 表添加 L3 需要的新列
@@ -257,7 +260,7 @@ export function arbitrateDispute(db, disputeId, arbitratorId, ruling, reason, re
  *
  * 这样确保托管资金守恒（无凭空创造/销毁），责任方额外受罚（去向：sys_protocol）。
  */
-function executeLiabilitySplit(db, orderId, liabilityParties, buyerRefund) {
+export function executeLiabilitySplit(db, orderId, liabilityParties, buyerRefund) {
     const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
     if (!order)
         return { success: false, error: '订单不存在' };
@@ -268,91 +271,78 @@ function executeLiabilitySplit(db, orderId, liabilityParties, buyerRefund) {
     const product = db.prepare('SELECT stake_amount FROM products WHERE id = ?')
         .get(order.product_id);
     const stakeAmount = product?.stake_amount ?? 0;
-    const actualRefund = Math.min(buyerRefund ?? totalAmount, totalAmount);
-    const sellerEscrowShare = Math.round((totalAmount - actualRefund) * 100) / 100;
-    // 预先计算各责任方实际扣款（资金守恒：责任方扣款 = 协议金库收入）
+    // RFC-014:整数 base-units
+    const totalU = toUnits(totalAmount);
+    const stakeAmountU = toUnits(stakeAmount);
+    const actualRefundU = Math.min(toUnits(buyerRefund ?? totalAmount), totalU);
+    const sellerEscrowShareU = totalU - actualRefundU; // 残值,精确
+    // 预先计算各责任方实际扣款（资金守恒：责任方扣款 = 协议金库收入），全整数 units
     const settled = [];
     for (const entry of liabilityParties) {
-        const wallet = db.prepare('SELECT balance, staked FROM wallets WHERE user_id = ?')
+        const wallet = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked FROM wallets WHERE user_id = ?')
             .get(entry.user_id);
-        const available = (wallet?.balance ?? 0) + (wallet?.staked ?? 0);
-        let actualPenalty;
-        let insuranceCovered = 0;
-        if (entry.insurance_cap !== undefined && entry.insurance_cap < entry.amount) {
+        const availableU = toUnits(wallet?.balance ?? 0) + toUnits(wallet?.staked ?? 0);
+        const amountU = toUnits(entry.amount);
+        let actualPenaltyU;
+        let insuranceCoveredU = 0;
+        if (entry.insurance_cap !== undefined && toUnits(entry.insurance_cap) < amountU) {
             // 有保险上限：责任方最多赔 insurance_cap，不足部分由协议垫付
-            actualPenalty = Math.min(entry.insurance_cap, available);
-            insuranceCovered = entry.amount - entry.insurance_cap; // 协议垫付
+            const capU = toUnits(entry.insurance_cap);
+            actualPenaltyU = Math.min(capU, availableU);
+            insuranceCoveredU = amountU - capU; // 协议垫付(信息性,不实际入账)
         }
         else {
             // 无保险上限：以实际可用余额为上限
-            actualPenalty = Math.min(entry.amount, available);
-            insuranceCovered = entry.amount - actualPenalty; // 余额不足部分
+            actualPenaltyU = Math.min(amountU, availableU);
+            insuranceCoveredU = amountU - actualPenaltyU; // 余额不足部分
         }
-        settled.push({ userId: entry.user_id, role: entry.role, owed: entry.amount, actualPenalty, insuranceCovered });
+        settled.push({ userId: entry.user_id, role: entry.role, owedU: amountU, actualPenaltyU, insuranceCoveredU });
     }
     // 卖家是否在责任方列表中
     const sellerLiability = liabilityParties.find(p => p.user_id === sellerId);
     db.transaction(() => {
         // ── A. 托管拨付 ──────────────────────────────────────────────
-        // 释放买家托管，退还 actualRefund 给买家，剩余给卖家
-        db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
-        if (actualRefund > 0) {
-            db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(actualRefund, buyerId);
-        }
-        if (sellerEscrowShare > 0) {
-            db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerEscrowShare, sellerId);
-        }
-        // ── B. 责任罚款 → 协议金库 ────────────────────────────────────
-        let totalToTreasury = 0;
+        applyWalletDelta(db, buyerId, { escrowed: -totalU });
+        if (actualRefundU > 0)
+            applyWalletDelta(db, buyerId, { balance: actualRefundU });
+        if (sellerEscrowShareU > 0)
+            applyWalletDelta(db, sellerId, { balance: sellerEscrowShareU });
+        // ── B. 责任罚款 → 协议金库（先质押后余额）─────────────────────
+        let totalToTreasuryU = 0;
         for (const s of settled) {
-            if (s.actualPenalty > 0) {
-                const w = db.prepare('SELECT balance, staked FROM wallets WHERE user_id = ?')
-                    .get(s.userId);
-                if (w.staked >= s.actualPenalty) {
-                    db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(s.actualPenalty, s.userId);
-                }
-                else {
-                    const fromStake = w.staked;
-                    const fromBalance = s.actualPenalty - fromStake;
-                    db.prepare('UPDATE wallets SET staked = 0, balance = balance - ? WHERE user_id = ?').run(fromBalance, s.userId);
-                }
-                totalToTreasury += s.actualPenalty;
-            }
-        }
-        if (totalToTreasury > 0) {
-            db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(totalToTreasury, sysUser.id);
+            if (s.actualPenaltyU > 0)
+                totalToTreasuryU += debitStakeThenBalance(db, s.userId, s.actualPenaltyU);
         }
+        if (totalToTreasuryU > 0)
+            applyWalletDelta(db, sysUser.id, { balance: totalToTreasuryU });
         // ── C. 卖家商品质押处理 ───────────────────────────────────────
-        if (stakeAmount > 0) {
+        if (stakeAmountU > 0) {
             if (sellerLiability) {
-                // 卖家有责：按责任金额比例扣罚质押，剩余返还
-                const stakeForfeited = Math.min(stakeAmount, sellerLiability.amount);
-                const stakeReturn = stakeAmount - stakeForfeited;
-                db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(stakeAmount, sellerId);
-                if (stakeReturn > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(stakeReturn, sellerId);
-                }
-                if (stakeForfeited > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(stakeForfeited, sysUser.id);
-                }
+                // 卖家有责：按责任金额扣罚质押(封顶),剩余返还
+                const stakeForfeitedU = Math.min(stakeAmountU, toUnits(sellerLiability.amount));
+                const stakeReturnU = stakeAmountU - stakeForfeitedU;
+                applyWalletDelta(db, sellerId, { staked: -stakeAmountU });
+                if (stakeReturnU > 0)
+                    applyWalletDelta(db, sellerId, { balance: stakeReturnU });
+                if (stakeForfeitedU > 0)
+                    applyWalletDelta(db, sysUser.id, { balance: stakeForfeitedU });
             }
             else {
                 // 卖家无责：全额返还质押
-                db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                    .run(stakeAmount, stakeAmount, sellerId);
+                applyWalletDelta(db, sellerId, { staked: -stakeAmountU, balance: stakeAmountU });
             }
         }
-        transition(db, orderId, 'refunded_partial', sysUser.id, [], `争议裁定：责任分配，退款买家 ${actualRefund} WAZ`);
+        transition(db, orderId, 'refunded_partial', sysUser.id, [], `争议裁定：责任分配，退款买家 ${toDecimal(actualRefundU)} WAZ`);
     })();
     return {
         success: true,
         detail: {
             ruling: 'liability_split',
-            buyer_refund: actualRefund,
-            seller_escrow_share: sellerEscrowShare,
+            buyer_refund: toDecimal(actualRefundU),
+            seller_escrow_share: toDecimal(sellerEscrowShareU),
             liability_breakdown: settled.map(s => ({
                 userId: s.userId, role: s.role,
-                owed: s.owed, actualPenalty: s.actualPenalty, insuranceCovered: s.insuranceCovered
+                owed: toDecimal(s.owedU), actualPenalty: toDecimal(s.actualPenaltyU), insuranceCovered: toDecimal(s.insuranceCoveredU)
             })),
         }
     };
@@ -366,35 +356,27 @@ function executeLiabilitySplit(db, orderId, liabilityParties, buyerRefund) {
  * - 先扣质押，质押不足再扣余额
  */
 function chargeArbitrationFee(db, loserId, orderAmount, arbitratorId, sysUserId) {
-    const fee = Math.max(1, Math.round(orderAmount * 0.01 * 100) / 100);
+    // RFC-014:整数 base-units。费 = max(1 WAZ, 订单额×1%)
+    const feeU = Math.max(toUnits(1), mulRate(toUnits(orderAmount), 0.01));
     const isHumanArbitrator = arbitratorId !== sysUserId;
-    const wallet = db.prepare('SELECT balance, staked FROM wallets WHERE user_id = ?')
+    const wallet = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked FROM wallets WHERE user_id = ?')
         .get(loserId);
-    const available = (wallet?.balance ?? 0) + (wallet?.staked ?? 0);
-    const actualFee = Math.min(fee, available);
-    if (actualFee <= 0)
+    const availableU = toUnits(wallet?.balance ?? 0) + toUnits(wallet?.staked ?? 0);
+    const actualFeeU = Math.min(feeU, availableU);
+    if (actualFeeU <= 0)
         return { fee: 0, arbitratorShare: 0, protocolShare: 0 };
     // 扣款：先质押后余额
-    const staked = wallet?.staked ?? 0;
-    if (staked >= actualFee) {
-        db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(actualFee, loserId);
-    }
-    else {
-        const fromBalance = actualFee - staked;
-        db.prepare('UPDATE wallets SET staked = 0, balance = balance - ? WHERE user_id = ?').run(fromBalance, loserId);
-    }
-    // 分配：人工仲裁各一半，自动裁定全归协议
-    const arbitratorShare = isHumanArbitrator ? Math.round(actualFee * 0.5 * 100) / 100 : 0;
-    const protocolShare = actualFee - arbitratorShare;
-    if (protocolShare > 0) {
-        db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(protocolShare, sysUserId);
-    }
-    if (arbitratorShare > 0) {
-        db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(arbitratorShare, arbitratorId);
-    }
-    return { fee: actualFee, arbitratorShare, protocolShare };
+    debitStakeThenBalance(db, loserId, actualFeeU);
+    // 分配：人工仲裁各一半(allocate 精确),自动裁定全归协议
+    const arbitratorShareU = isHumanArbitrator ? allocate(actualFeeU, [1, 1])[0] : 0;
+    const protocolShareU = actualFeeU - arbitratorShareU;
+    if (protocolShareU > 0)
+        applyWalletDelta(db, sysUserId, { balance: protocolShareU });
+    if (arbitratorShareU > 0)
+        applyWalletDelta(db, arbitratorId, { balance: arbitratorShareU });
+    return { fee: toDecimal(actualFeeU), arbitratorShare: toDecimal(arbitratorShareU), protocolShare: toDecimal(protocolShareU) };
 }
-function executeSettlement(db, orderId, ruling, refundAmount, liablePartyId) {
+export function executeSettlement(db, orderId, ruling, refundAmount, liablePartyId) {
     const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
     if (!order)
         return { success: false, error: '订单不存在' };
@@ -405,143 +387,131 @@ function executeSettlement(db, orderId, ruling, refundAmount, liablePartyId) {
         .get(order.product_id);
     const stakeAmount = product?.stake_amount ?? 0;
     const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
+    // RFC-014:整数 base-units
+    const totalU = toUnits(totalAmount);
+    const stakeAmountU = toUnits(stakeAmount);
     if (ruling === 'refund_buyer') {
-        // ── 买家胜诉：退全款 + 卖家损失一半质押（惩罚）──────────────
-        const penalty = Math.round(stakeAmount * 0.5 * 100) / 100;
-        const stakeReturn = stakeAmount - penalty;
+        // ── 买家胜诉：退全款 + 卖家损失一半质押（惩罚,allocate 精确二分）──────────────
+        const [penaltyU, stakeReturnU] = stakeAmountU > 0 ? allocate(stakeAmountU, [1, 1]) : [0, 0];
         db.transaction(() => {
             // 退还买家托管资金
-            db.prepare('UPDATE wallets SET escrowed = escrowed - ?, balance = balance + ? WHERE user_id = ?')
-                .run(totalAmount, totalAmount, buyerId);
-            // 卖家扣押质押 → 一半补偿给买家，一半归协议
-            if (stakeAmount > 0) {
-                db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(stakeAmount, sellerId);
-                if (penalty > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(penalty, buyerId);
-                }
+            applyWalletDelta(db, buyerId, { escrowed: -totalU, balance: totalU });
+            // 卖家扣押全额质押 → 一半补偿买家,一半退回卖家(净损一半)
+            if (stakeAmountU > 0) {
+                applyWalletDelta(db, sellerId, { staked: -stakeAmountU });
+                if (penaltyU > 0)
+                    applyWalletDelta(db, buyerId, { balance: penaltyU });
+                if (stakeReturnU > 0)
+                    applyWalletDelta(db, sellerId, { balance: stakeReturnU });
             }
-            transition(db, orderId, 'refunded_full', sysUser.id, [], `争议裁定：退款买家，质押惩罚 ${penalty} WAZ`);
+            transition(db, orderId, 'refunded_full', sysUser.id, [], `争议裁定：退款买家，质押惩罚 ${toDecimal(penaltyU)} WAZ`);
         })();
         return {
             success: true,
             detail: {
                 ruling: 'refund_buyer',
-                buyer_refund: totalAmount,
-                buyer_compensation: penalty,
-                seller_stake_forfeited: stakeAmount,
-                seller_stake_returned: stakeReturn,
+                buyer_refund: toDecimal(totalU),
+                buyer_compensation: toDecimal(penaltyU),
+                seller_stake_forfeited: toDecimal(stakeAmountU),
+                seller_stake_returned: toDecimal(stakeReturnU),
             }
         };
     }
     else if (ruling === 'release_seller') {
         // ── 卖家胜诉：资金释放给卖家（正常结算逻辑）──────────────────
-        const protocolFee = Math.round(totalAmount * 0.02 * 100) / 100;
-        const logisticsFee = order.logistics_id ? Math.round(totalAmount * 0.05 * 100) / 100 : 0;
-        const sellerAmount = totalAmount - protocolFee - logisticsFee;
+        const protocolFeeU = mulRate(totalU, 0.02);
+        const logisticsFeeU = order.logistics_id ? mulRate(totalU, 0.05) : 0;
+        const sellerAmountU = totalU - protocolFeeU - logisticsFeeU; // 残值
         db.transaction(() => {
-            db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
-            db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerAmount, sellerId);
-            if (order.logistics_id && logisticsFee > 0) {
-                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(logisticsFee, order.logistics_id);
-            }
-            // 返还卖家质押
-            if (stakeAmount > 0) {
-                db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                    .run(stakeAmount, stakeAmount, sellerId);
-            }
+            applyWalletDelta(db, buyerId, { escrowed: -totalU });
+            applyWalletDelta(db, sellerId, { balance: sellerAmountU });
+            if (order.logistics_id && logisticsFeeU > 0)
+                applyWalletDelta(db, order.logistics_id, { balance: logisticsFeeU });
+            if (protocolFeeU > 0)
+                applyWalletDelta(db, sysUser.id, { balance: protocolFeeU }); // 协议费入金库
+            if (stakeAmountU > 0)
+                applyWalletDelta(db, sellerId, { staked: -stakeAmountU, balance: stakeAmountU }); // 返还质押
             transition(db, orderId, 'resolved_for_seller', sysUser.id, [], '争议裁定：卖家胜诉，资金释放完成');
         })();
         return {
             success: true,
             detail: {
                 ruling: 'release_seller',
-                seller_received: sellerAmount,
-                logistics_fee: logisticsFee,
-                protocol_fee: protocolFee,
-                seller_stake_returned: stakeAmount,
+                seller_received: toDecimal(sellerAmountU),
+                logistics_fee: toDecimal(logisticsFeeU),
+                protocol_fee: toDecimal(protocolFeeU),
+                seller_stake_returned: toDecimal(stakeAmountU),
             }
         };
     }
     else if (ruling === 'partial_refund') {
-        const refund = refundAmount ?? Math.round(totalAmount * 0.5 * 100) / 100;
-        if (refund > totalAmount)
-            return { success: false, error: `退款金额 ${refund} 超出订单总额 ${totalAmount}` };
+        const refundU = refundAmount != null ? toUnits(refundAmount) : mulRate(totalU, 0.5);
+        if (refundU > totalU)
+            return { success: false, error: `退款金额 ${toDecimal(refundU)} 超出订单总额 ${totalAmount}` };
         if (liablePartyId) {
             // ── 第三方责任 partial_refund ────────────────────────────────
             // 卖家全额结算（正常收款），买家赔偿由责任方钱包直接支付
-            const protocolFee = Math.round(totalAmount * 0.02 * 100) / 100;
-            const logisticsFee = order.logistics_id ? Math.round(totalAmount * 0.05 * 100) / 100 : 0;
-            const sellerAmount = totalAmount - protocolFee - logisticsFee;
+            const protocolFeeU = mulRate(totalU, 0.02);
+            const logisticsFeeU = order.logistics_id ? mulRate(totalU, 0.05) : 0;
+            const sellerAmountU = totalU - protocolFeeU - logisticsFeeU;
             // 检查责任方余额是否足够
-            const liableWallet = db.prepare('SELECT balance, staked FROM wallets WHERE user_id = ?')
+            const liableWallet = db.prepare('SELECT COALESCE(balance,0) balance, COALESCE(staked,0) staked FROM wallets WHERE user_id = ?')
                 .get(liablePartyId);
-            const liableAvailable = (liableWallet?.balance ?? 0) + (liableWallet?.staked ?? 0);
-            const actualRefund = Math.min(refund, liableAvailable);
+            const liableAvailableU = toUnits(liableWallet?.balance ?? 0) + toUnits(liableWallet?.staked ?? 0);
+            const actualRefundU = Math.min(refundU, liableAvailableU);
             db.transaction(() => {
                 // 1. 释放托管 → 正常结算给卖家
-                db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
-                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerAmount, sellerId);
-                if (order.logistics_id && logisticsFee > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(logisticsFee, order.logistics_id);
-                }
+                applyWalletDelta(db, buyerId, { escrowed: -totalU });
+                applyWalletDelta(db, sellerId, { balance: sellerAmountU });
+                if (order.logistics_id && logisticsFeeU > 0)
+                    applyWalletDelta(db, order.logistics_id, { balance: logisticsFeeU });
+                if (protocolFeeU > 0)
+                    applyWalletDelta(db, sysUser.id, { balance: protocolFeeU }); // 协议费入金库
                 // 2. 返还卖家质押
-                if (stakeAmount > 0) {
-                    db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                        .run(stakeAmount, stakeAmount, sellerId);
-                }
-                // 3. 从责任方钱包扣除赔偿（先质押后余额）
-                if (actualRefund > 0) {
-                    const liableStaked = liableWallet?.staked ?? 0;
-                    if (liableStaked >= actualRefund) {
-                        db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(actualRefund, liablePartyId);
-                    }
-                    else {
-                        const fromBalance = actualRefund - liableStaked;
-                        db.prepare('UPDATE wallets SET staked = 0, balance = balance - ? WHERE user_id = ?').run(fromBalance, liablePartyId);
-                    }
-                    // 4. 赔偿金给买家
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(actualRefund, buyerId);
+                if (stakeAmountU > 0)
+                    applyWalletDelta(db, sellerId, { staked: -stakeAmountU, balance: stakeAmountU });
+                // 3. 从责任方钱包扣赔偿(先质押后余额) → 4. 给买家
+                if (actualRefundU > 0) {
+                    debitStakeThenBalance(db, liablePartyId, actualRefundU);
+                    applyWalletDelta(db, buyerId, { balance: actualRefundU });
                 }
-                transition(db, orderId, 'refunded_partial', sysUser.id, [], `争议裁定：第三方责任赔偿 ${actualRefund} WAZ，卖家全额结算`);
+                transition(db, orderId, 'refunded_partial', sysUser.id, [], `争议裁定：第三方责任赔偿 ${toDecimal(actualRefundU)} WAZ，卖家全额结算`);
             })();
             return {
                 success: true,
                 detail: {
                     ruling: 'partial_refund',
                     liable_party: liablePartyId,
-                    buyer_compensation: actualRefund,
-                    seller_received: sellerAmount,
-                    logistics_fee: logisticsFee,
-                    protocol_fee: protocolFee,
-                    seller_stake_returned: stakeAmount,
+                    buyer_compensation: toDecimal(actualRefundU),
+                    seller_received: toDecimal(sellerAmountU),
+                    logistics_fee: toDecimal(logisticsFeeU),
+                    protocol_fee: toDecimal(protocolFeeU),
+                    seller_stake_returned: toDecimal(stakeAmountU),
                 }
             };
         }
         else {
-            // ── 买卖双方协商 partial_refund（原逻辑）───────────────────────
-            const sellerGet = Math.round((totalAmount - refund) * 100) / 100;
-            const stakeReturn = Math.round(stakeAmount * 0.5 * 100) / 100; // 质押返一半
+            // ── 买卖双方协商 partial_refund ───────────────────────
+            const sellerGetU = totalU - refundU;
+            // 政策(option a):协商和解无过错 → 全额退质押,不罚没。
+            const stakeReturnU = stakeAmountU;
             db.transaction(() => {
-                db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
-                if (refund > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(refund, buyerId);
-                }
-                if (sellerGet > 0) {
-                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerGet, sellerId);
-                }
-                if (stakeAmount > 0) {
-                    db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                        .run(stakeAmount, stakeReturn, sellerId);
-                }
-                transition(db, orderId, 'refunded_partial', sysUser.id, [], `争议裁定：部分退款 ${refund} WAZ`);
+                applyWalletDelta(db, buyerId, { escrowed: -totalU });
+                if (refundU > 0)
+                    applyWalletDelta(db, buyerId, { balance: refundU });
+                if (sellerGetU > 0)
+                    applyWalletDelta(db, sellerId, { balance: sellerGetU });
+                if (stakeAmountU > 0)
+                    applyWalletDelta(db, sellerId, { staked: -stakeAmountU, balance: stakeReturnU });
+                transition(db, orderId, 'refunded_partial', sysUser.id, [], `争议裁定：部分退款 ${toDecimal(refundU)} WAZ`);
             })();
             return {
                 success: true,
                 detail: {
                     ruling: 'partial_refund',
-                    buyer_refund: refund,
-                    seller_received: sellerGet,
-                    seller_stake_returned: stakeReturn,
+                    buyer_refund: toDecimal(refundU),
+                    seller_received: toDecimal(sellerGetU),
+                    seller_stake_returned: toDecimal(stakeReturnU),
                 }
             };
         }

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

@@ -16,6 +16,8 @@
  *   - 其他技能目前免费（增强曝光，间接提升成交）
  */
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { toUnits, toDecimal } from '../../money.js';
+import { applyWalletDelta } from '../../ledger.js';
 // ─── Schema ───────────────────────────────────────────────────
 export function initSkillSchema(db) {
     db.exec(`
@@ -223,15 +225,15 @@ export function recordSkillUsage(db, orderId, orderAmount) {
   `).get(order.buyer_id, order.seller_id);
     if (!skillSub)
         return;
-    const fee = Math.round(orderAmount * 0.005 * 100) / 100; // 0.5% 推荐佣金
-    if (fee <= 0)
+    const feeU = Math.round(toUnits(orderAmount) * 0.005); // 0.5% 推荐佣金(整数 base-units)
+    if (feeU <= 0)
         return;
     // 从系统账户（protocol fee 池）拨出佣金给 Skill 发布者
     // 简化实现：直接增加卖家钱包余额（Skill 发布者就是卖家本人）
-    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(fee, skillSub.seller_id);
+    applyWalletDelta(db, skillSub.seller_id, { balance: feeU });
     db.prepare('UPDATE skills SET total_uses = total_uses + 1 WHERE id = ?').run(skillSub.skill_id);
     const id = generateId('sul');
-    db.prepare('INSERT INTO skill_usage_log (id, skill_id, user_id, order_id, fee_paid) VALUES (?,?,?,?,?)').run(id, skillSub.skill_id, order.buyer_id, orderId, fee);
+    db.prepare('INSERT INTO skill_usage_log (id, skill_id, user_id, order_id, fee_paid) VALUES (?,?,?,?,?)').run(id, skillSub.skill_id, order.buyer_id, orderId, toDecimal(feeU));
 }
 // ─── 自动接单 Skill 触发 ──────────────────────────────────────
 /**

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

@@ -18,6 +18,8 @@
  *   绝不进入 PV 二元匹配 / 推土机三级佣金 / fund_base —— 保持双引擎解耦、规避 PV 合规问题。
  */
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { toUnits, toDecimal } from '../../money.js';
+import { applyWalletDelta } from '../../ledger.js';
 export const SKILL_KINDS = ['template', 'prompt', 'guide', 'checklist'];
 export const SKILL_BILLING_MODES = ['free', 'one_time', 'per_use'];
 export const SKILL_KIND_META = {
@@ -231,18 +233,20 @@ function hasUnlock(db, userId, listingId) {
 }
 /** 扣买家、加作者净额、协议费入 sys_protocol；记 skill_orders。feeRate 由路由层从协议参数传入。 */
 function settlePayment(db, listing, buyerId, feeRate) {
-    const price = Number(listing.price);
-    const fee = Math.round(price * feeRate * 100) / 100;
-    const net = Math.round((price - fee) * 100) / 100;
+    // RFC-014:整数 base-units(买家付 price = 作者净额 net + 协议费 fee,精确守恒)
+    const priceU = toUnits(Number(listing.price));
+    const feeU = Math.round(priceU * feeRate);
+    const netU = priceU - feeU; // 残值,精确
+    const price = toDecimal(priceU), fee = toDecimal(feeU), net = toDecimal(netU);
     const tx = db.transaction(() => {
         const w = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(buyerId);
-        if (!w || w.balance < price)
+        if (!w || toUnits(w.balance) < priceU)
             throw new Error('余额不足，请先充值');
-        db.prepare('UPDATE wallets SET balance = balance - ? WHERE user_id = ?').run(price, buyerId);
-        db.prepare('UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?').run(net, net, listing.author_id);
+        applyWalletDelta(db, buyerId, { balance: -priceU });
+        applyWalletDelta(db, listing.author_id, { balance: netU, earned: netU });
         db.prepare("INSERT OR IGNORE INTO wallets (user_id, balance) VALUES ('sys_protocol', 0)").run();
-        if (fee > 0)
-            db.prepare("UPDATE wallets SET balance = balance + ? WHERE user_id = 'sys_protocol'").run(fee);
+        if (feeU > 0)
+            applyWalletDelta(db, 'sys_protocol', { balance: feeU });
         db.prepare('UPDATE skill_listings SET total_sales = total_sales + 1, total_revenue = total_revenue + ? WHERE id = ?').run(price, listing.id);
         db.prepare('INSERT INTO skill_orders (id, listing_id, buyer_id, billing_mode, amount_paid, protocol_fee, author_net) VALUES (?,?,?,?,?,?,?)')
             .run(generateId('sko'), listing.id, buyerId, listing.billing_mode, price, fee, net);

package/dist/ledger.js

@@ -0,0 +1,58 @@
+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) };
+}
+/**
+ * 对钱包字段施加整数单位 delta,以【绝对值】落库(读当前→加 delta→写 toDecimal)。
+ *   - 字段白名单固定(balance/staked/escrowed/earned),无 SQL 注入面。
+ *   - 钱包行不存在 → UPDATE 影响 0 行(与历史相对更新的静默行为一致)。
+ *   - 必须在调用方的 transaction 内使用(资金路径本就如此)。
+ */
+export function applyWalletDelta(db, userId, deltas) {
+    const fields = Object.keys(deltas).filter(f => deltas[f] !== undefined && deltas[f] !== 0);
+    if (fields.length === 0)
+        return;
+    const cur = walletUnits(db, userId);
+    const sets = [];
+    const vals = [];
+    for (const f of fields) {
+        sets.push(`${f} = ?`);
+        vals.push(toDecimal(cur[f] + deltas[f]));
+    }
+    vals.push(userId);
+    db.prepare(`UPDATE wallets SET ${sets.join(', ')} WHERE user_id = ?`).run(...vals);
+}
+/**
+ * 从某用户【先扣 staked,不足再扣 balance】,封顶其可用额(staked+balance,不转负)。返回实扣 units。
+ *   争议罚没/仲裁费常用:质押优先承担,质押不够再动自由余额。绝对值落库,无浮点 dust。
+ */
+export function debitStakeThenBalance(db, userId, amountU) {
+    const cur = walletUnits(db, userId);
+    const avail = Math.max(0, cur.staked) + Math.max(0, cur.balance);
+    const actual = Math.min(Math.max(0, amountU), avail);
+    if (actual <= 0)
+        return 0;
+    const fromStaked = Math.min(actual, Math.max(0, cur.staked));
+    const fromBalance = actual - fromStaked;
+    applyWalletDelta(db, userId, { staked: -fromStaked, balance: -fromBalance });
+    return actual;
+}
+/**
+ * 通用基金/池表的【绝对值】入账(整数 base-units):读当前→加 delta→写 toDecimal。
+ *   用于 global_fund / management_bonus_pool / commission_reserve / charity_fund 等单行池表。
+ *   table / 列名 / whereClause 均为【代码字面量】(非用户输入)→ 无 SQL 注入面。
+ *   行不存在 → UPDATE 影响 0 行(与历史相对更新一致)。
+ */
+export function creditColumns(db, table, whereClause, whereArgs, deltas) {
+    const cols = Object.keys(deltas).filter(c => deltas[c] !== 0);
+    if (cols.length === 0)
+        return;
+    const cur = db.prepare(`SELECT ${cols.map(c => `COALESCE(${c},0) AS ${c}`).join(', ')} FROM ${table} WHERE ${whereClause}`)
+        .get(...whereArgs);
+    const sets = cols.map(c => `${c} = ?`).join(', ');
+    const vals = cols.map(c => toDecimal(toUnits(cur?.[c] ?? 0) + deltas[c]));
+    db.prepare(`UPDATE ${table} SET ${sets} WHERE ${whereClause}`).run(...vals, ...whereArgs);
+}