@seasonkoh/webaz 0.1.21 → 0.1.23

package/dist/pwa/routes/referral.js

@@ -55,4 +55,85 @@ export function registerReferralRoutes(app, deps) {
         logAdminAction(admin.id, 'invite_rotation_toggle', 'system', 'invite_rotation_enabled', { value: v });
         res.json({ success: true, enabled: !!enabled });
     });
+    // RFC-003 #1122: 生成商品分享链接(把 MCP webaz_share_link 的本地计算搬到服务端,
+    // 让 MCP NETWORK 模式可代理)。RFC-002 §3.5 valuation-layer gate:需 rewards opt-in。
+    // 与 PWA pickPreferredSide 对齐的 side 选择(team_count | pv_count)。
+    app.get('/api/share-link', (req, res) => {
+        const user = auth(req, res);
+        if (!user)
+            return;
+        const userId = user.id;
+        const productId = String(req.query.product_id || '');
+        const sideArg = String(req.query.side || 'auto');
+        if (!productId)
+            return void res.status(400).json({ error: 'product_id required', error_code: 'PRODUCT_ID_REQUIRED' });
+        const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
+        if (optIn !== 1) {
+            const getParam = (key, def) => {
+                const r = db.prepare("SELECT value FROM protocol_params WHERE key = ?").get(key);
+                return r ? Number(r.value) : def;
+            };
+            const minOrders = getParam('rewards_opt_in.min_completed_orders', 1);
+            const requirePasskey = getParam('rewards_opt_in.require_passkey', 1);
+            const totalCompleted = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
+            const passkeyCount = db.prepare("SELECT COUNT(*) as n FROM webauthn_credentials WHERE user_id = ?").get(userId).n;
+            const missing = [];
+            if (totalCompleted < minOrders)
+                missing.push(`completed_orders ${totalCompleted}/${minOrders}`);
+            if (requirePasskey === 1 && passkeyCount === 0)
+                missing.push('passkey_not_registered');
+            if (missing.length === 0)
+                missing.push('application_not_submitted');
+            return void res.status(403).json({
+                error: 'rewards_opt_in_required',
+                message: 'Share-link generation is a valuation-layer action — requires builder-identity opt-in (RFC-002 §3.5)',
+                missing_requirements: missing,
+                next_steps: [
+                    'Open PWA #me → tap "申请共建身份 / Apply for builder identity"',
+                    'Read the 8-second disclosure (cannot skip)',
+                    'Submit application — pre-checks run server-side',
+                ],
+            });
+        }
+        const product = db.prepare("SELECT id, title, price, commission_rate FROM products WHERE id = ? AND status='active'").get(productId);
+        if (!product)
+            return void res.status(404).json({ error: '商品不存在或已下架', error_code: 'PRODUCT_NOT_FOUND' });
+        let side = 'right';
+        if (sideArg === 'left' || sideArg === 'right') {
+            side = sideArg;
+        }
+        else {
+            const u = db.prepare("SELECT placement_pref, total_left_pv, total_right_pv, left_count, right_count FROM users WHERE id = ?")
+                .get(userId);
+            const pref = u?.placement_pref || 'team_count';
+            if (pref === 'pv_count') {
+                const since = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString().slice(0, 19).replace('T', ' ');
+                const w = db.prepare(`SELECT COALESCE(SUM(consumed_left_pv),0) AS l, COALESCE(SUM(consumed_right_pv),0) AS r
+                              FROM binary_score_records WHERE user_id = ? AND created_at >= ?`)
+                    .get(userId, since);
+                const leftPv = Number(u?.total_left_pv ?? 0) + Number(w.l);
+                const rightPv = Number(u?.total_right_pv ?? 0) + Number(w.r);
+                side = leftPv <= rightPv ? 'left' : 'right';
+            }
+            else {
+                side = (Number(u?.left_count ?? 0) <= Number(u?.right_count ?? 0)) ? 'left' : 'right';
+            }
+        }
+        const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
+        const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
+        const canL1 = override === 1 || (override === 0 && completed > 0);
+        const rate = Number(product.commission_rate ?? 0);
+        const link = `/?ref=${userId}&side=${side}#order-product/${productId}`;
+        res.json({
+            product: { id: product.id, title: product.title, price: product.price, commission_rate: rate },
+            share_link: link,
+            full_url_hint: 'Prepend webaz.xyz (production) to get the absolute URL',
+            side,
+            binary_explanation: `New user via this link → placed in your ${side === 'left' ? '🔵 left' : '🟢 right'} subtree (tail anchor)`,
+            commission_eligibility: canL1
+                ? `You will earn 3-tier commission: L1=${(rate * 0.70 * 100).toFixed(1)}% L2=${(rate * 0.20 * 100).toFixed(1)}% L3=${(rate * 0.10 * 100).toFixed(1)}% of sale price`
+                : 'You are NOT verified yet (need 1 completed purchase). 3-tier commission will be skipped, but points-matching still builds.',
+            next_steps: 'Share on TikTok / WeChat / Telegram. New user clicks → 30-day attribution window starts.',
+        });
+    });
 }

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.23",
   "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": {