@seasonkoh/webaz 0.1.21 → 0.1.22

package/dist/pwa/server.js

@@ -24,6 +24,10 @@ import { initSystemUser, transition, getOrderStatus, checkTimeouts, settleFault
 import { endpointToAction, endpointToReadAction } from './endpoint-actions.js';
 import { AGENT_RATE_PER_MIN_DEFAULTS, CROSS_USER_READ_DAILY_CAP, MASS_ACTION_TYPES, MASS_ACTION_DAILY_CAPS } from './limits.js';
 import { initOrderChainSchema, appendOrderEvent, getOrderChain, verifyOrderChain } from '../layer0-foundation/L0-2-state-machine/order-chain.js';
+// RFC-014 PR4 — 正常成交结算走整数 base-units + allocate + 绝对值落库。
+import { toUnits, toDecimal, mulRate, allocate } from '../money.js';
+import { applyWalletDelta, creditColumns } from '../ledger.js';
+import { computeSettlementSplit } from '../settlement-math.js';
 import { initSnfSchema, snfSend, snfCleanup } from '../layer2-business/L2-7-snf/snf-engine.js';
 import { initExternalAnchorSchema } from '../layer1-agent/L1-2-external-anchor/anchor-engine.js';
 import { ensureEvidenceColumns, uploadEvidence, listEvidence as listEvidenceFiles, markEvidenceExpiry, cleanupExpiredEvidence, EVIDENCE_MAX_BYTES, EVIDENCE_ALLOWED_MIME, } from '../layer3-trust/L3-1-dispute-engine/evidence-storage.js';
@@ -8667,7 +8671,9 @@ function settleCommission(orderId, effectiveBase) {
         region = buyer?.region ?? 'global';
     }
     const maxLevels = getRegionMaxLevels(region);
-    const pool = Math.round(total * rate * 100) / 100;
+    // RFC-014:佣金池 + 三级拆分走整数 base-units;allocate 保证 L1+L2+L3 ≡ pool(精确,修旧版逐项 round2 不守恒暗缝)。
+    const poolU = mulRate(toUnits(total), rate);
+    const pool = toDecimal(poolU);
     // max_levels=0 → 完全禁 MLM，整个 commission pool 入 commission_reserve（三级公池，只进不出）
     // 2026-06-04 修双计 bug：旧版既 redirectToCharity 又 return redirected:pool 让 depositToFund 再入 global_fund → 印钱。
     // 现统一入 commission_reserve 一次，return redirected:0（depositToFund 只拿 1% base）。
@@ -8706,9 +8712,12 @@ function settleCommission(orderId, effectiveBase) {
     // 2026-06-04：所有兜底统一入 commission_reserve（三级公池，独立科目，只进不出）。
     // commission 不再回流 global_fund（PV 资金）—— 三套科目解耦，redirected 始终 0。
     let toCommissionReserve = 0; // → commission_reserve（仅作日志/返回信息用）
+    // 三级金额一次性 allocate(精确求和 ≡ poolU);各级再按 gate 路由到钱包/公池/escrow。
+    const levelAmtU = allocate(poolU, [LEVEL_RATES[1], LEVEL_RATES[2], LEVEL_RATES[3]]);
     for (const { level, beneficiary } of recipients) {
-        const amount = Math.round(pool * LEVEL_RATES[level] * 100) / 100;
-        if (amount <= 0)
+        const amountU = levelAmtU[level - 1];
+        const amount = toDecimal(amountU);
+        if (amountU <= 0)
             continue;
         // ① region 截断 (level>maxLevels) → 三级公池
         if (level > maxLevels) {
@@ -8756,8 +8765,7 @@ function settleCommission(orderId, effectiveBase) {
             db.prepare(`INSERT INTO commission_records (id, order_id, beneficiary_id, source_buyer_id, level, amount, rate, region, source, source_type)
                   VALUES (?,?,?,?,?,?,?,?,?,?)`)
                 .run(generateId('comm'), orderId, beneficiary, order.buyer_id, level, amount, rate, region, routeSource, srcType);
-            db.prepare("UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?")
-                .run(amount, amount, beneficiary);
+            applyWalletDelta(db, beneficiary, { balance: amountU, earned: amountU });
         }
         catch (e) { /* UNIQUE 冲突 */ }
     }
@@ -8829,22 +8837,30 @@ function depositToFund(orderId, extraFromCommission = 0, effectiveBase) {
     const total = effectiveBase != null ? Number(effectiveBase) : Number(order.total_amount);
     if (total <= 0)
         return { base: 0, redirect: 0, total: 0 };
-    const amountBase = Math.round(total * FUND_BASE_RATE() * 100) / 100;
-    const amountRedirect = Math.round(Number(extraFromCommission || 0) * 100) / 100;
+    // RFC-014:整数 base-units + 绝对值落库
+    const amountBaseU = mulRate(toUnits(total), FUND_BASE_RATE());
+    const amountRedirectU = toUnits(Number(extraFromCommission || 0));
     const region = order.buyer_region || 'global';
-    const totalDeposit = Math.round((amountBase + amountRedirect) * 100) / 100;
-    if (totalDeposit > 0) {
+    const totalDepositU = amountBaseU + amountRedirectU;
+    const amountBase = toDecimal(amountBaseU);
+    const amountRedirect = toDecimal(amountRedirectU);
+    const totalDeposit = toDecimal(totalDepositU);
+    if (totalDepositU > 0) {
         // fund_deposits.amount_l3 字段语义已扩为「commission 端回流总额」（区域裁决 + 未 verified）
         db.prepare(`INSERT INTO fund_deposits (id, order_id, amount_base, amount_l3, buyer_region)
                 VALUES (?,?,?,?,?)`).run(generateId('fd'), orderId, amountBase, amountRedirect, region);
-        db.prepare("UPDATE global_fund SET pool_balance = pool_balance + ? WHERE id = 1").run(totalDeposit);
+        creditColumns(db, 'global_fund', 'id = 1', [], { pool_balance: totalDepositU });
     }
     return { base: amountBase, redirect: amountRedirect, total: totalDeposit };
 }
 function redirectToCommissionReserve(amount, kind, args = {}) {
     if (!Number.isFinite(amount) || amount <= 0)
         return;
-    const a = Math.round(amount * 100) / 100;
+    // RFC-014:整数 base-units + 绝对值落库(防 REAL `col = col + ?` 浮点 dust)。
+    const aU = toUnits(amount);
+    if (aU <= 0)
+        return;
+    const a = toDecimal(aU);
     // Aggregate column mapping (commission_reserve_txns.kind records exact kind):
     //   chain_gap → total_chain_gap
     //   orphan_sponsor / opt_out_deactivated / escrow_expired → total_orphan_sponsor (no-eligible-recipient bucket)
@@ -8853,7 +8869,8 @@ function redirectToCommissionReserve(amount, kind, args = {}) {
         : kind === 'redirect_region_cap' ? 'total_region_cap'
             : 'total_orphan_sponsor';
     db.transaction(() => {
-        db.prepare(`UPDATE commission_reserve SET balance = balance + ?, ${totalCol} = ${totalCol} + ?, updated_at = datetime('now') WHERE id = 'main'`).run(a, a);
+        creditColumns(db, 'commission_reserve', "id = 'main'", [], { balance: aU, [totalCol]: aU });
+        db.prepare(`UPDATE commission_reserve SET updated_at = datetime('now') WHERE id = 'main'`).run();
         db.prepare(`INSERT INTO commission_reserve_txns (id, kind, from_user_id, amount, related_order_id, note)
                 VALUES (?,?,?,?,?,?)`).run(generateId('crt'), kind, args.fromUserId || null, a, args.orderId || null, args.note || null);
     })();
@@ -8872,19 +8889,11 @@ function settleOrder(orderId) {
             : db.prepare('SELECT stake_amount, stake_locked_at, category_id FROM products WHERE id = ?').get(order.product_id);
         // M8：协议费率二手 1% (vs 商家 2%) — 鼓励个人发布
         const feeRate = isSecondhand ? 0.01 : 0.02;
-        const protocolFee = Math.round(total * feeRate * 100) / 100;
-        const protocolToBonus = Math.round(protocolFee * 0.5 * 100) / 100;
-        const protocolToOps = Math.round((protocolFee - protocolToBonus) * 100) / 100;
-        // 面交无三方物流 → logisticsFee = 0
-        const logisticsFee = isInPerson ? 0 : Math.round(total * 0.05 * 100) / 100;
-        // P0 2026-05-28：self-fulfill（logistics_id NULL）订单 → 不收 5% 物流费，全额给 seller
-        // 之前 sellerAmount 用 logisticsFee 扣，但 line 7780 不付任何人 → 每笔黑洞 5% × total
-        const logisticsActual = order.logistics_id ? logisticsFee : 0;
         // QA 轮 9.4 P0：settleOrder default 0 vs settleCommission default 0.10 不一致 → 印钱漏洞
         // 修：统一两处 default = 0.10（跟 PWA orders-create.ts:277 一致）
         const commissionRate = Number(order.snapshot_commission_rate ?? 0.10);
-        const commissionPool = Math.round(total * commissionRate * 100) / 100;
-        const fundBase = Math.round(total * FUND_BASE_RATE() * 100) / 100;
+        // RFC-014:实际拆分在下方 computeSettlementSplit(整数 base-units,卖家净额 residual 吸收 → 精确守恒)。
+        //   self-fulfill / 面交不收物流费(chargeLogistics=false);协议费 50/50 由 allocate 精确拆。
         // M7.2.6 方案 3 + M-4 fix：首单锁定 stake（trusted+ 跳过）
         // 用单语句 UPDATE ... WHERE stake_locked_at IS NULL 原子拿"是否首次"判定，
         // 避免读后写竞态（旧实现两条语句，迁 PG / 多 worker 时可能双锁）
@@ -8902,21 +8911,30 @@ function settleOrder(orderId) {
                     stakeToLock = product.stake_amount;
             }
         }
-        // sellerAmount 扣掉首单要锁的 stake
-        const sellerAmount = Math.round((total - protocolFee - logisticsActual - commissionPool - fundBase - stakeToLock) * 100) / 100;
-        db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(total, order.buyer_id);
-        db.prepare('UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?').run(sellerAmount, sellerAmount, order.seller_id);
-        if (order.logistics_id)
-            db.prepare('UPDATE wallets SET balance = balance + ?, earned = earned + ? WHERE user_id = ?').run(logisticsFee, logisticsFee, order.logistics_id);
-        // 首单时把 stake 划入 staked（来自 sellerAmount，已扣除）
-        if (stakeToLock > 0) {
-            db.prepare('UPDATE wallets SET staked = staked + ? WHERE user_id = ?').run(stakeToLock, order.seller_id);
-        }
+        // RFC-014:整数 base-units 精确拆分(卖家净额 = total − 其余各项,residual 吸收 → Σ ≡ total)。
+        const totalU = toUnits(total);
+        const split = computeSettlementSplit({
+            totalU,
+            feeRate,
+            logisticsRate: 0.05,
+            chargeLogistics: !isInPerson && !!order.logistics_id, // self-fulfill / 面交 = 不收物流费
+            commissionRate,
+            fundRate: FUND_BASE_RATE(),
+            stakeToLockU: toUnits(stakeToLock),
+        });
+        // 买家 escrow 释放 + 卖家净额 + 物流费(实扣即实付)+ 首单 stake 锁定 —— 全绝对值落库
+        applyWalletDelta(db, order.buyer_id, { escrowed: -totalU });
+        applyWalletDelta(db, order.seller_id, { balance: split.sellerAmountU, earned: split.sellerAmountU });
+        if (order.logistics_id && split.logisticsActualU > 0) {
+            applyWalletDelta(db, order.logistics_id, { balance: split.logisticsActualU, earned: split.logisticsActualU });
+        }
+        if (split.stakeToLockU > 0)
+            applyWalletDelta(db, order.seller_id, { staked: split.stakeToLockU });
         // 协议费拆分：50% 注入管理津贴池，50% 入 sys_protocol 运营
-        if (protocolToBonus > 0)
-            db.prepare("UPDATE management_bonus_pool SET balance = balance + ? WHERE id = 1").run(protocolToBonus);
-        if (protocolToOps > 0)
-            db.prepare("UPDATE wallets SET balance = balance + ? WHERE user_id = 'sys_protocol'").run(protocolToOps);
+        if (split.protocolToBonusU > 0)
+            creditColumns(db, 'management_bonus_pool', 'id = 1', [], { balance: split.protocolToBonusU });
+        if (split.protocolToOpsU > 0)
+            applyWalletDelta(db, 'sys_protocol', { balance: split.protocolToOpsU });
         // 推土机分享分润：正常分账 → 钱包；兜底 → commission_reserve（三级公池，独立科目）
         settleCommission(orderId);
         // 原子能：PV 资金池入金 = 仅 1% base（2026-06-04 起 commission 不再回流此池，三科目解耦）
@@ -8987,9 +9005,9 @@ function settleOrder(orderId) {
             }
             // P0.1：RFQ 订单完单成功 → 释放卖家 bid_stake_held（staked → balance）+ synthetic product 转 warehouse（P1.2 顺手修）
             try {
-                const heldStake = Number(order.bid_stake_held || 0);
-                if (heldStake > 0 && order.source === 'rfq') {
-                    db.prepare('UPDATE wallets SET balance = balance + ?, staked = staked - ? WHERE user_id = ?').run(heldStake, heldStake, order.seller_id);
+                const heldStakeU = toUnits(Number(order.bid_stake_held || 0));
+                if (heldStakeU > 0 && order.source === 'rfq') {
+                    applyWalletDelta(db, order.seller_id, { balance: heldStakeU, staked: -heldStakeU });
                 }
                 // synthetic RFQ product（描述以 [RFQ 开头）卖完后转 warehouse，防 active feed 污染
                 const pInfo = db.prepare('SELECT description, stock FROM products WHERE id = ?').get(order.product_id);

package/dist/settlement-math.js

@@ -0,0 +1,27 @@
+/**
+ * Settlement split — settleOrder 正常成交的资金拆分【纯函数】(RFC-014,可测)。
+ *
+ * 把买家托管的 total 拆成:协议费(再 50/50 拆津贴/运营)+ 物流费 + 佣金池 + 基金 1% + 首单锁定 stake
+ *   + 卖家净额。卖家净额 = total − 其余各项(residual 吸收)→ 整数单位下【精确守恒】(Σ ≡ total)。
+ *
+ * server.ts settleOrder 直接调用本函数拿数字,再落库(applyWalletDelta/creditColumns)。
+ * 守恒由 tests/test-settlement-math.ts 守(此前 settleOrder 在 server.ts 巨石里、绑 db 闭包,无法隔离单测)。
+ */
+import { mulRate, allocate } from './money.js';
+export function computeSettlementSplit(i) {
+    const protocolFeeU = mulRate(i.totalU, i.feeRate);
+    const [protocolToBonusU, protocolToOpsU] = allocate(protocolFeeU, [1, 1]); // 精确 50/50
+    const logisticsFeeU = mulRate(i.totalU, i.logisticsRate);
+    const logisticsActualU = i.chargeLogistics ? logisticsFeeU : 0;
+    const commissionPoolU = mulRate(i.totalU, i.commissionRate);
+    const fundBaseU = mulRate(i.totalU, i.fundRate);
+    const stakeToLockU = i.stakeToLockU;
+    // 卖家净额 = 残值 → 保证 Σ ≡ total(整数减法精确,不增发/不丢)
+    const sellerAmountU = i.totalU - protocolFeeU - logisticsActualU - commissionPoolU - fundBaseU - stakeToLockU;
+    return { protocolFeeU, protocolToBonusU, protocolToOpsU, logisticsFeeU, logisticsActualU, commissionPoolU, fundBaseU, stakeToLockU, sellerAmountU };
+}
+/** 守恒校验(供测试 + 运行期可选断言):各去向之和 ≡ total。 */
+export function settlementConserves(totalU, s) {
+    return s.protocolToBonusU + s.protocolToOpsU === s.protocolFeeU
+        && s.protocolFeeU + s.logisticsActualU + s.commissionPoolU + s.fundBaseU + s.stakeToLockU + s.sellerAmountU === totalU;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "[PRE-LAUNCH] Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools. ⚠️ Repository currently private until W8 public launch — GitHub links may return 404. See https://webaz.xyz for status.",
   "main": "dist/mcp.js",
   "bin": {