@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/direct-pay-fee-prepay-request.js

@@ -0,0 +1,80 @@
+import { getPlatformAccount } from './platform-receive-accounts.js';
+import { recordFeePrepayTopup } from './direct-pay-fee-ar.js';
+export const MAX_EVIDENCE_LEN = 200;
+export const MAX_EVIDENCE_NOTE_LEN = 500;
+const COLS = 'id, seller_id, amount_units, currency, platform_account_id, evidence_ref, evidence_note, status, created_at, reviewed_by, reviewed_at, review_note, resulting_payment_id';
+/** 卖家发起预充值申请。校验:金额正整数、凭据必填(不能无据)、平台收款方式须为 active。建 pending。不动钱。 */
+export function createFeePrepayRequest(db, sellerId, input, generateId) {
+    const amount = Number(input.amountUnits);
+    if (!Number.isSafeInteger(amount) || amount <= 0)
+        return { ok: false, reason: 'amount must be a positive integer (base units)' }; // 严格整数,不静默截断非整数
+    const evidenceRef = String(input.evidenceRef ?? '').trim();
+    if (!evidenceRef)
+        return { ok: false, reason: '付款凭证号必填(不能无据)' };
+    if (evidenceRef.length > MAX_EVIDENCE_LEN)
+        return { ok: false, reason: `evidence_ref must be ≤ ${MAX_EVIDENCE_LEN} chars` };
+    const note = input.evidenceNote == null ? null : String(input.evidenceNote).trim().slice(0, MAX_EVIDENCE_NOTE_LEN) || null;
+    const currency = input.currency == null || !String(input.currency).trim() ? null : String(input.currency).trim().toUpperCase().slice(0, 8);
+    // platform_account_id 必填 + 必须 active:充值必须对准一个 WebAZ 收款账户,admin 才能据此核对到账来源(不能无账户的半场外流程)。
+    const pid = input.platformAccountId == null ? '' : String(input.platformAccountId).trim();
+    if (!pid)
+        return { ok: false, reason: '必须选择平台收款方式' };
+    const acc = getPlatformAccount(db, pid);
+    if (!acc || acc.status !== 'active')
+        return { ok: false, reason: '所选平台收款方式无效或已停用' };
+    const id = generateId('fpr');
+    db.prepare(`INSERT INTO direct_pay_fee_prepay_requests (id, seller_id, amount_units, currency, platform_account_id, evidence_ref, evidence_note, status) VALUES (?,?,?,?,?,?,?, 'pending')`)
+        .run(id, sellerId, amount, currency, pid, evidenceRef, note);
+    return { ok: true, request: getRequest(db, id) };
+}
+/** 卖家自己的申请(全状态,新→旧)。 */
+export function listSellerRequests(db, sellerId) {
+    return db.prepare(`SELECT ${COLS} FROM direct_pay_fee_prepay_requests WHERE seller_id = ? ORDER BY created_at DESC, id DESC`).all(sellerId);
+}
+export function getRequest(db, id) {
+    return db.prepare(`SELECT ${COLS} FROM direct_pay_fee_prepay_requests WHERE id = ?`).get(id) ?? null;
+}
+/** 卖家撤销自己的 pending 申请(owner-scoped;仅 pending 可撤)。返回是否改动。 */
+export function cancelRequest(db, id, sellerId) {
+    return db.prepare("UPDATE direct_pay_fee_prepay_requests SET status='cancelled', reviewed_at=datetime('now') WHERE id=? AND seller_id=? AND status='pending'").run(id, sellerId).changes > 0;
+}
+/** admin 队列:按状态列出所有卖家的申请(pending 升序供审核;无状态时取最近)。 */
+export function listAllRequests(db, status) {
+    if (status)
+        return db.prepare(`SELECT ${COLS} FROM direct_pay_fee_prepay_requests WHERE status = ? ORDER BY created_at ASC, id ASC`).all(status);
+    return db.prepare(`SELECT ${COLS} FROM direct_pay_fee_prepay_requests ORDER BY created_at DESC, id DESC LIMIT 200`).all();
+}
+/**
+ * admin 确认真实到账 → 入账(【唯一动钱处】)。原子:pending→approved + recordFeePrepayTopup(记 direct_pay_fee_payments,
+ *   带申请的 evidence_ref)+ 回填 resulting_payment_id,全在一个 tx。非 pending / 记账失败 → 整体回滚不动钱。method=usdc|fiat。
+ */
+export function approveFeePrepayRequest(db, args) {
+    if (args.method !== 'usdc' && args.method !== 'fiat')
+        return { ok: false, error: 'BAD_METHOD' };
+    const req = getRequest(db, args.requestId);
+    if (!req)
+        return { ok: false, error: 'REQUEST_NOT_FOUND' };
+    if (req.status !== 'pending')
+        return { ok: false, error: 'NOT_PENDING' };
+    let paymentId = '';
+    try {
+        db.transaction(() => {
+            const r = recordFeePrepayTopup(db, { sellerId: req.seller_id, amountUnits: req.amount_units, method: args.method, recordedBy: args.adminId, evidenceRef: req.evidence_ref, note: args.reviewNote ?? undefined });
+            if (!r.ok)
+                throw new Error(r.error);
+            const upd = db.prepare("UPDATE direct_pay_fee_prepay_requests SET status='approved', reviewed_by=?, reviewed_at=datetime('now'), review_note=?, resulting_payment_id=? WHERE id=? AND status='pending'").run(args.adminId, args.reviewNote ?? null, r.id, args.requestId);
+            if (upd.changes !== 1)
+                throw new Error('NOT_PENDING'); // 并发保险:非 pending → 回滚(含刚记的 topup)
+            paymentId = r.id;
+        })();
+    }
+    catch (e) {
+        return { ok: false, error: e.message };
+    }
+    return { ok: true, paymentId };
+}
+/** admin 驳回 pending 申请(不动钱)。返回 ok / 非 pending。 */
+export function rejectFeePrepayRequest(db, args) {
+    const upd = db.prepare("UPDATE direct_pay_fee_prepay_requests SET status='rejected', reviewed_by=?, reviewed_at=datetime('now'), review_note=? WHERE id=? AND status='pending'").run(args.adminId, args.reviewNote ?? null, args.requestId);
+    return upd.changes === 1 ? { ok: true } : { ok: false, error: 'NOT_PENDING' };
+}

package/dist/direct-pay-launch-readiness.js

@@ -0,0 +1,108 @@
+import { readDirectPayControlsConfig, sellerDirectPayBreakerTripped, sellerDirectPayKybPassed, sellerDirectPaySanctionsClear, sellerDirectPayAmlClear, } from './direct-pay-controls.js';
+import { sellerHasProductionBaseBondLocked } from './direct-receive-deposits.js';
+import { sellerBaseBondEntrySatisfied } from './direct-pay-base-bond-entry.js';
+import { getActiveDeferral } from './direct-receive-deferral.js';
+import { bondRailClearanceBlockers, isBondRailClearedForProduction } from './direct-pay-bond-rail-clearance.js';
+import { getActivePaymentInstruction } from './direct-receive-payment-instruction.js';
+/** 候选生产 base-bond 收款轨(与 #112 registry 一致;manual 是非生产确认轨,不算)。 */
+// 候选生产 base-bond 收款轨。operator_attested(#116,已实现的运营核实轨)是 v1 实际要用的那条,必须纳入诊断,
+//   否则它被 registry 放行后 readiness 仍误报"无 legal-cleared rail"。manual=非生产确认轨,不算。
+const PRODUCTION_BOND_RAILS = ['operator_attested', 'usdc_onchain', 'fiat_psp'];
+/**
+ * 只读 readiness 汇总。args.getProtocolParam 读控制面配置;args.sellerId 提供时附加 seller-specific blockers。
+ * ready ⟺ blockers 为空。绝不写库。
+ */
+export function readDirectPayLaunchReadiness(db, args) {
+    const { getProtocolParam, sellerId } = args;
+    const cfg = readDirectPayControlsConfig(getProtocolParam);
+    const blockers = [];
+    // ── global / policy(镜像 evaluateDirectPayLaunchControls 的非订单条件;不短路,收集全部)──
+    if (cfg.enabled !== true)
+        blockers.push('DIRECT_PAY_NOT_ENABLED');
+    if (cfg.railBreakerTripped === true)
+        blockers.push('DIRECT_PAY_RAIL_BREAKER_TRIPPED');
+    const allow = Array.isArray(cfg.regionAllowlist) ? cfg.regionAllowlist : [];
+    if (!allow.length || !cfg.region || !allow.includes(cfg.region))
+        blockers.push('DIRECT_PAY_REGION_NOT_ALLOWED');
+    if (!(Number.isSafeInteger(cfg.perTxCapUnits) && cfg.perTxCapUnits > 0))
+        blockers.push('DIRECT_PAY_PER_TX_CAP_UNSET');
+    // ── production bond-rail clearance(#112;rail-level,jurisdiction-aware)── 【诊断 facts,非 launch blocker】
+    //   关键:真实建单/可用性门(evaluateDirectPayLaunchControls + direct-pay-create/availability)从不校验 rail-clearance。
+    //   rail-clearance 只 gate【有人交真实保证金】这一条路(confirmProductionReceipt 的 Lock B);缓交卖家根本不交 bond,
+    //   也就不需要任何 cleared rail 即可直付。因此把 rail-clearance 当全局 launch blocker 会让 readiness 误报"未开放"——
+    //   与真实门不一致(Codex #117 P1)。这里只【计算并下发为诊断 facts】(anyRailLegalCleared / perRailClearance),
+    //   供运营判断"若要接收真实保证金,bonded-deposit 轨是否就绪",但绝不进 blockers / 不影响 ready / PLATFORM_OPEN。
+    const perRailClearance = {};
+    for (const rid of PRODUCTION_BOND_RAILS)
+        perRailClearance[rid] = bondRailClearanceBlockers(rid, { hasProductionReceipt: true });
+    // jurisdiction-aware:把【当前部署 region】传进去,校验 region ∈ rail 的 legal jurisdictionAllowlist(coarse 判定会误报 cleared)。
+    const anyRailLegalCleared = PRODUCTION_BOND_RAILS.some(rid => isBondRailClearedForProduction(rid, cfg.region));
+    // ── seller-specific(仅当传入 sellerId)──
+    let sellerSuspended = null, productionBaseBondLocked = null;
+    let activeDeferral = null, baseBondSatisfied = null;
+    let kybPassed = null, sanctionsClear = null, amlClear = null;
+    let paymentInstructionPresent = null;
+    if (sellerId) {
+        const nowIso = new Date().toISOString();
+        sellerSuspended = sellerDirectPayBreakerTripped(db, sellerId);
+        productionBaseBondLocked = sellerHasProductionBaseBondLocked(db, sellerId);
+        activeDeferral = getActiveDeferral(db, sellerId, nowIso) != null;
+        // 镜像 create gate(direct-pay-base-bond-entry):保证金门 = 生产 bond OR 有效缓交。
+        baseBondSatisfied = sellerBaseBondEntrySatisfied(db, sellerId, nowIso);
+        kybPassed = sellerDirectPayKybPassed(db, sellerId);
+        sanctionsClear = sellerDirectPaySanctionsClear(db, sellerId);
+        amlClear = sellerDirectPayAmlClear(db, sellerId);
+        // 镜像真实建单硬门(direct-pay-create.ts):无 active 收款说明 → create 返回 NO_PAYMENT_INSTRUCTION,绝不建单。
+        paymentInstructionPresent = getActivePaymentInstruction(db, sellerId) != null;
+        if (sellerSuspended)
+            blockers.push('DIRECT_PAY_SELLER_SUSPENDED');
+        // 与 create gate 一致:有生产 bond 或有效缓交即满足;两者都无才 blocker。
+        if (!baseBondSatisfied)
+            blockers.push('DIRECT_PAY_SELLER_NO_PRODUCTION_BASE_BOND');
+        if (!kybPassed)
+            blockers.push('DIRECT_PAY_SELLER_KYB_NOT_APPROVED');
+        if (!sanctionsClear)
+            blockers.push('DIRECT_PAY_SELLER_SANCTIONS_NOT_CLEARED');
+        if (!amlClear)
+            blockers.push('DIRECT_PAY_SELLER_AML_REVIEW_REQUIRED');
+        if (!paymentInstructionPresent)
+            blockers.push('DIRECT_PAY_SELLER_PAYMENT_INSTRUCTION_MISSING');
+    }
+    return {
+        ready: blockers.length === 0,
+        blockers,
+        facts: {
+            enabled: cfg.enabled, railBreakerTripped: cfg.railBreakerTripped, region: cfg.region,
+            regionAllowlist: cfg.regionAllowlist, perTxCapUnits: cfg.perTxCapUnits,
+            perRailClearance, anyRailLegalCleared,
+            sellerEvaluated: !!sellerId, sellerId: sellerId ?? null,
+            sellerSuspended, productionBaseBondLocked, activeDeferral, baseBondSatisfied, kybPassed, sanctionsClear, amlClear, paymentInstructionPresent,
+        },
+    };
+}
+// PLATFORM_OPEN 只折叠【真实全局建单门】(镜像 evaluateDirectPayLaunchControls 的非订单条件):enabled / rail-breaker /
+//   region / per-tx cap。rail-clearance 不在此列(它不 gate 直付,见上),否则缓交卖家会被误显示"平台未开放"。
+const GLOBAL_LAUNCH_BLOCKERS = new Set([
+    'DIRECT_PAY_NOT_ENABLED', 'DIRECT_PAY_RAIL_BREAKER_TRIPPED', 'DIRECT_PAY_REGION_NOT_ALLOWED', 'DIRECT_PAY_PER_TX_CAP_UNSET',
+]);
+/**
+ * 卖家脱敏 readiness 视图。复用 readDirectPayLaunchReadiness(只读),把内部 blockers/facts 折叠成卖家安全的项目集。
+ * 输出【不含】任何 raw blocker code、KYB/sanctions/AML 分项或法务/rail 细节。纯读。
+ */
+export function sellerDirectPayReadinessView(db, args) {
+    const { getProtocolParam, sellerId } = args;
+    const r = readDirectPayLaunchReadiness(db, { getProtocolParam, sellerId });
+    const f = r.facts;
+    const platformOpen = !r.blockers.some(b => GLOBAL_LAUNCH_BLOCKERS.has(b));
+    const hasPasskey = !!db.prepare('SELECT 1 FROM webauthn_credentials WHERE user_id = ? LIMIT 1').get(sellerId);
+    const complianceCleared = f.kybPassed === true && f.sanctionsClear === true && f.amlClear === true; // 折叠;不分项
+    const items = [
+        { code: 'PLATFORM_OPEN', ok: platformOpen, actionable: false },
+        { code: 'PAYMENT_INSTRUCTION', ok: f.paymentInstructionPresent === true, actionable: true },
+        { code: 'PASSKEY', ok: hasPasskey, actionable: true },
+        { code: 'BASE_BOND', ok: f.baseBondSatisfied === true, actionable: false }, // 生产 bond 或有效缓交即算满足(与 create gate 一致)
+        { code: 'COMPLIANCE_REVIEW', ok: complianceCleared, actionable: false },
+        { code: 'NOT_SUSPENDED', ok: f.sellerSuspended === false, actionable: false },
+    ];
+    return { directPayReady: items.every(i => i.ok), items };
+}

package/dist/direct-pay-launch-summary.js

@@ -0,0 +1,68 @@
+import { readDirectPayLaunchReadiness } from './direct-pay-launch-readiness.js';
+import { readDirectPayControlsConfig } from './direct-pay-controls.js';
+import { checkDeferralQuota, readDeferralQuotaConfig } from './direct-pay-deferral-quota.js';
+import { productStoreVerified } from './product-verification.js';
+import { sellerExemptFromPerProduct } from './store-verification.js';
+import { toUnits } from './money.js';
+/** 候选卖家:在任一 direct-pay 相关表里出现过的卖家(有意接入直付者)。 */
+function candidateSellers(db) {
+    const rows = db.prepare(`
+    SELECT DISTINCT seller_id FROM (
+      SELECT seller_id FROM direct_receive_payment_instructions WHERE status = 'active'
+      UNION SELECT user_id   FROM direct_receive_deferrals
+      UNION SELECT user_id   FROM direct_receive_deposits
+      UNION SELECT seller_id FROM product_verifications
+      UNION SELECT user_id   FROM store_verifications
+    ) WHERE seller_id IS NOT NULL
+  `).all();
+    return rows.map(r => r.seller_id);
+}
+/** 聚合 go/no-go。纯读。getProtocolParam 由调用方按部署注入(CLI 从 protocol_params 构造)。 */
+export function summarizeDirectPayLaunchReadiness(db, getProtocolParam) {
+    const globalRd = readDirectPayLaunchReadiness(db, { getProtocolParam }); // 无 sellerId → 仅全局 blockers
+    const global = { ready: globalRd.blockers.length === 0, blockers: globalRd.blockers, facts: globalRd.facts };
+    const globalSet = new Set(global.blockers);
+    const nowIso = new Date().toISOString();
+    const quotaCfg = readDeferralQuotaConfig(getProtocolParam);
+    const controlsCfg = readDirectPayControlsConfig(getProtocolParam);
+    const sellers = candidateSellers(db).map(sellerId => {
+        const rd = readDirectPayLaunchReadiness(db, { getProtocolParam, sellerId });
+        // 仅 seller-specific blockers(去掉全局 blockers,避免每个卖家都重复挂全局问题)。
+        const sellerBlockers = rd.blockers.filter(b => !globalSet.has(b));
+        const ready = sellerBlockers.length === 0;
+        const storeExempt = sellerExemptFromPerProduct(db, sellerId);
+        const products = db.prepare("SELECT id, price, stock, has_variants FROM products WHERE seller_id = ? AND status = 'active'").all(sellerId);
+        // 可直付商品 = 必须能真正走 direct_p2p 建单(镜像 create gate / evaluateDirectPayLaunchControls + 建单库存门),全部满足:
+        //   ① 简单商品(direct_p2p v1 拒规格商品 has_variants=1);② 逐品 verified 或卖家店铺豁免;
+        //   ③ 单笔上限:amount>0 且 ≤ perTxCapUnits(且 cap 已配 >0)—— 镜像 DIRECT_PAY_CAP_EXCEEDED;
+        //   ④ 有货(stock≥1)—— 镜像 createDirectPayOrder 的 `stock >= qty`(否则 'stock depleted');
+        //   ⑤ 无进行中限时促销(direct_p2p v1 拒 flash_sale=DIRECT_PAY_UNSUPPORTED_OPTION;谓词镜像 getActiveFlashSale@flash-sales.ts 的简单商品分支);
+        //   ⑥ 通过缓交额度(checkDeferralQuota qty=1 该单价;非缓交卖家=no-op)。否则报告会误判 go=true 而真实下单被拒。
+        const flashActive = db.prepare(`SELECT 1 FROM flash_sales WHERE product_id = ? AND is_active = 1
+      AND starts_at <= datetime('now') AND ends_at > datetime('now') AND (max_qty = 0 OR sold_count < max_qty) AND variant_id IS NULL LIMIT 1`);
+        const eligibleProductCount = products.filter(p => {
+            const priceU = toUnits(Number(p.price) || 0);
+            return Number(p.has_variants) !== 1
+                && (storeExempt || productStoreVerified(db, p.id))
+                && controlsCfg.perTxCapUnits > 0 && priceU > 0 && priceU <= controlsCfg.perTxCapUnits
+                && Number(p.stock) >= 1
+                && !flashActive.get(p.id)
+                && checkDeferralQuota(db, sellerId, priceU, nowIso, quotaCfg).ok;
+        }).length;
+        return { sellerId, ready, blockers: sellerBlockers, storeExempt, activeProductCount: products.length, eligibleProductCount, launchable: ready && eligibleProductCount > 0 };
+    });
+    const launchableSellerCount = sellers.filter(s => s.launchable).length;
+    // PRE-FLIP 自检:忽略【且仅忽略】"总开关未开"这一项,回答"除了翻 enabled,还差什么"。其余(region/cap/卖家/商品)照常要求。
+    const preflipReady = global.blockers.filter(b => b !== 'DIRECT_PAY_NOT_ENABLED').length === 0;
+    const pendingEnable = global.facts.enabled !== true;
+    return {
+        go: global.ready && launchableSellerCount > 0, // LIVE(含 enabled)
+        preflipGo: preflipReady && launchableSellerCount > 0, // 只差翻 enabled 即就绪
+        pendingEnable,
+        global, sellers, launchableSellerCount,
+    };
+}
+/** 便捷:从控制面配置取关键运营数值(供 CLI 打印)。 */
+export function directPayControlsSnapshot(getProtocolParam) {
+    return readDirectPayControlsConfig(getProtocolParam);
+}

package/dist/direct-pay-ledger.js

@@ -0,0 +1,94 @@
+import { toUnits, toDecimal, allocate } from './money.js';
+import { applyWalletDelta, walletUnits, creditColumns } from './ledger.js';
+/**
+ * penalty 科目【唯一】写入口(只进,无对应出账函数)。
+ *   - source='fee_stake' → 真入 WAZ balance(fee-stake 本就是 WAZ)。
+ *   - source='base_bond' → 仅记 provenance 计数(外部资产,真实处置 gated;不进 balance)。
+ */
+function creditPenalty(db, opts) {
+    const { kind, source, fromUserId = null, amountU, relatedOrderId = null, reason = null, txnId } = opts;
+    const deltas = source === 'fee_stake'
+        ? { balance: amountU, total_fee_stake_slash: amountU } // WAZ 真入池
+        : { total_base_bond_slash: amountU }; // 外部资产:仅计数,不进 balance
+    creditColumns(db, 'penalty_fund', "id = 'main'", [], deltas);
+    db.prepare("UPDATE penalty_fund SET updated_at = datetime('now') WHERE id = 'main'").run();
+    db.prepare(`INSERT INTO penalty_fund_txns (id, kind, source, from_user_id, amount, related_order_id, reason, created_at) VALUES (?,?,?,?,?,?,?,datetime('now'))`)
+        .run(txnId, kind, source, fromUserId, toDecimal(amountU), relatedOrderId, reason);
+}
+function getStake(db, orderId) {
+    return db.prepare('SELECT id, order_id, seller_id, amount, status FROM direct_pay_fee_stakes WHERE order_id = ?')
+        .get(orderId);
+}
+/** 只读断言:订单是否有【locked】fee-stake(可在完成时取费)。完成路径预检用,缺则拒绝 direct_p2p 进 completed。 */
+export function hasLockedFeeStake(db, orderId) {
+    return getStake(db, orderId)?.status === 'locked';
+}
+/** 锁定逐单费用质押(= 平台费):卖家可用余额 → fee_staked。余额不足返回 {ok:false}(调用方不开单)。 */
+export function lockFeeStake(db, opts) {
+    const { orderId, sellerId, feeUnits, stakeId } = opts;
+    if (feeUnits <= 0)
+        return { ok: false, reason: 'fee must be > 0' };
+    if (getStake(db, orderId))
+        return { ok: false, reason: 'fee-stake already exists for order' };
+    const w = walletUnits(db, sellerId);
+    if (w.balance < feeUnits)
+        return { ok: false, reason: 'insufficient balance for fee-stake' };
+    applyWalletDelta(db, sellerId, { balance: -feeUnits, fee_staked: feeUnits });
+    db.prepare(`INSERT INTO direct_pay_fee_stakes (id, order_id, seller_id, amount, status, created_at) VALUES (?,?,?,?, 'locked', datetime('now'))`)
+        .run(stakeId, orderId, sellerId, toDecimal(feeUnits));
+    return { ok: true };
+}
+/**
+ * 完成时取费:整笔 fee-stake → 协议(reserve 50% + sys_protocol 50%,与 settleOrder 协议费去向一致)。
+ * **FAIL-CLOSED(钱路不变量):** direct_p2p 单完成必须有可取的 locked fee-stake,否则平台费会被静默落空。
+ *   - 无 stake 行 / 状态非 locked 且非 fee_taken → **抛错**(调用方 settleOrder 在 db.transaction 内 → 回滚,
+ *     拒绝"完成但零平台费")。绝不静默 return(那正是审计 P1-2 指出的 fail-open 漏洞)。
+ *   - 已 fee_taken → 幂等:返回 'already_taken',不重复取费(支持重结算)。
+ * fee-stake == 平台费,故无 remainder(若将来 stake>fee 可在此退差额给卖家)。
+ */
+export function takeFeeAtCompletion(db, opts) {
+    const s = getStake(db, opts.orderId);
+    if (!s)
+        throw new Error(`takeFeeAtCompletion: no fee-stake for direct_p2p order ${opts.orderId} — refusing to settle without platform fee (fail-closed)`);
+    if (s.status === 'fee_taken')
+        return { outcome: 'already_taken' }; // 幂等:重结算不重复取费
+    if (s.status !== 'locked')
+        throw new Error(`takeFeeAtCompletion: fee-stake for order ${opts.orderId} is '${s.status}', not 'locked' — refusing to settle (fail-closed)`);
+    const feeU = toUnits(s.amount);
+    applyWalletDelta(db, s.seller_id, { fee_staked: -feeU });
+    const [toReserveU, toOpsU] = allocate(feeU, [1, 1]);
+    if (toReserveU > 0)
+        creditColumns(db, 'protocol_reserve_pool', 'id = 1', [], { balance: toReserveU });
+    if (toOpsU > 0)
+        applyWalletDelta(db, 'sys_protocol', { balance: toOpsU });
+    db.prepare("UPDATE direct_pay_fee_stakes SET status='fee_taken', settled_at=datetime('now') WHERE order_id=? AND status='locked'").run(opts.orderId);
+    return { outcome: 'taken' };
+}
+/** 释放(未付/取消/超时):整笔退回卖家可用余额。幂等。 */
+export function releaseFeeStake(db, opts) {
+    const s = getStake(db, opts.orderId);
+    if (!s || s.status !== 'locked')
+        return;
+    const feeU = toUnits(s.amount);
+    applyWalletDelta(db, s.seller_id, { fee_staked: -feeU, balance: feeU });
+    db.prepare("UPDATE direct_pay_fee_stakes SET status='released', settled_at=datetime('now') WHERE order_id=? AND status='locked'").run(opts.orderId);
+}
+/** 违约罚没:整笔 fee-stake → penalty 科目(feeRetainedOnFault=false → WebAZ 不收费,整笔入池)。幂等。 */
+export function slashFeeStakeToPenalty(db, opts) {
+    const s = getStake(db, opts.orderId);
+    if (!s || s.status !== 'locked')
+        return;
+    const feeU = toUnits(s.amount);
+    applyWalletDelta(db, s.seller_id, { fee_staked: -feeU });
+    creditPenalty(db, { kind: 'fee_stake_slash', source: 'fee_stake', fromUserId: s.seller_id, amountU: feeU, relatedOrderId: opts.orderId, reason: opts.reason ?? null, txnId: opts.txnId });
+    db.prepare("UPDATE direct_pay_fee_stakes SET status='slashed', settled_at=datetime('now') WHERE order_id=? AND status='locked'").run(opts.orderId);
+}
+/**
+ * base bond(外部担保物)罚没:仅记 provenance(total_base_bond_slash + txn),不进 WAZ balance。
+ * 真实外部资产(USDC/法币)处置 GATED(deposit-rail 非生产 / 法务)。由 Phase 4 deposit 生命周期调用。
+ */
+export function recordBaseBondSlash(db, opts) {
+    if (opts.amountUnits <= 0)
+        return;
+    creditPenalty(db, { kind: 'base_bond_slash', source: 'base_bond', fromUserId: opts.userId, amountU: opts.amountUnits, relatedOrderId: null, reason: opts.reason ?? null, txnId: opts.txnId });
+}

package/dist/direct-pay-returns.js

@@ -0,0 +1,104 @@
+function loadReturn(db, returnId) {
+    return db.prepare(`SELECT r.id, r.order_id, r.buyer_id, r.seller_id, r.product_id, r.status, r.reason,
+                            r.refund_amount, r.await_refund_since, o.payment_rail, o.total_amount AS order_total
+                     FROM return_requests r JOIN orders o ON o.id = r.order_id WHERE r.id = ?`).get(returnId);
+}
+export function returnRefundRespondDays(db) {
+    try {
+        const p = db.prepare("SELECT value FROM protocol_params WHERE key = 'direct_pay.return_refund_respond_days'").get();
+        if (p)
+            return Math.max(1, Number(p.value) || 5);
+    }
+    catch { /* 表缺失 → 默认 */ }
+    return 5;
+}
+/**
+ * 卖家同意退货后进入 await_refund(替代 escrow 的 executeReturnRefund)。
+ * fromStatus = 'pending'(同意·无取件)| 'picked_up'(取件流·确认收到退货)。CAS 防并发。
+ * 同 tx 内写协商时间线消息(与 escrow accept 同模式)。调用方负责通知。
+ */
+export function enterAwaitRefund(db, args) {
+    const rr = loadReturn(db, args.returnId);
+    if (!rr)
+        return { ok: false, error: '退货请求不存在', error_code: 'RETURN_NOT_FOUND' };
+    if (rr.payment_rail !== 'direct_p2p')
+        return { ok: false, error: '仅直付订单走场外退款握手', error_code: 'NOT_DIRECT_PAY' };
+    const resp = typeof args.sellerResponse === 'string' ? args.sellerResponse.slice(0, 500) : null;
+    const r = db.prepare(`UPDATE return_requests SET status = 'await_refund', await_refund_since = datetime('now'),
+                        seller_response = COALESCE(?, seller_response) WHERE id = ? AND status = ?`)
+        .run(resp, args.returnId, args.fromStatus);
+    if (r.changes !== 1)
+        return { ok: false, error: '退货请求已被处理(请刷新后查看)', error_code: 'RETURN_ALREADY_SETTLED' };
+    try {
+        db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
+            .run(args.messageId, rr.id, rr.seller_id, 'seller', `[✓ 同意退货 · 待场外退款] ${resp || ''}`);
+    }
+    catch { /* 时间线消息 best-effort */ }
+    return { ok: true, status: 'await_refund' };
+}
+/** 卖家声明已场外退款(await_refund → refund_marked,可附退款参考)。此后买家 confirm 或走争议。 */
+export function markReturnRefunded(db, args) {
+    const rr = loadReturn(db, args.returnId);
+    if (!rr)
+        return { ok: false, error: '退货请求不存在', error_code: 'RETURN_NOT_FOUND' };
+    if (rr.seller_id !== args.sellerId)
+        return { ok: false, error: '只有订单卖家可声明退款', error_code: 'NOT_ORDER_SELLER' };
+    if (rr.payment_rail !== 'direct_p2p')
+        return { ok: false, error: '仅直付订单走场外退款握手', error_code: 'NOT_DIRECT_PAY' };
+    const ref = typeof args.refundReference === 'string' ? args.refundReference.trim().slice(0, 200) : null;
+    const r = db.prepare(`UPDATE return_requests SET status = 'refund_marked', refund_reference = ? WHERE id = ? AND status = 'await_refund'`)
+        .run(ref, args.returnId);
+    if (r.changes !== 1)
+        return { ok: false, error: '当前状态不可声明退款(须先同意退货,或已被处理)', error_code: 'NOT_AWAIT_REFUND' };
+    try {
+        db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
+            .run(args.messageId, rr.id, rr.seller_id, 'seller', `[💸 已声明场外退款] ${ref ? `退款参考:${ref}` : ''}`);
+    }
+    catch { /* best-effort */ }
+    return { ok: true, status: 'refund_marked' };
+}
+/**
+ * 买家确认已收到场外退款(refund_marked → refunded,终态)。【必须由路由 db.transaction 包裹 + Passkey 门】。
+ * 全额退款 → completion_count -1(与 escrow 同口径的 best-effort 社交计数;无钱、无库存、无 clearing)。
+ */
+export function confirmReturnRefundReceived(db, args) {
+    const rr = loadReturn(db, args.returnId);
+    if (!rr)
+        return { ok: false, error: '退货请求不存在', error_code: 'RETURN_NOT_FOUND' };
+    if (rr.buyer_id !== args.buyerId)
+        return { ok: false, error: '只有订单买家可确认收到退款', error_code: 'NOT_ORDER_BUYER' };
+    if (rr.payment_rail !== 'direct_p2p')
+        return { ok: false, error: '仅直付订单走场外退款握手', error_code: 'NOT_DIRECT_PAY' };
+    const cas = db.prepare(`UPDATE return_requests SET status = 'refunded', resolved_at = datetime('now') WHERE id = ? AND status = 'refund_marked'`)
+        .run(args.returnId);
+    if (cas.changes !== 1)
+        return { ok: false, error: '卖家尚未声明退款,不可确认', error_code: 'REFUND_NOT_MARKED' };
+    if (Number(rr.refund_amount) >= Number(rr.order_total)) {
+        db.prepare(`UPDATE products SET completion_count = MAX(0, COALESCE(completion_count,0) - 1) WHERE id = ?`).run(rr.product_id);
+    }
+    try {
+        db.prepare(`INSERT INTO return_messages (id, return_id, sender_id, sender_role, body) VALUES (?,?,?,?,?)`)
+            .run(args.messageId, rr.id, rr.buyer_id, 'buyer', '[✅ 已确认收到场外退款] 退货完成');
+    }
+    catch { /* best-effort */ }
+    const SELLER_FAULT_REASONS = new Set(['quality', 'wrong_item', 'damaged']);
+    return {
+        ok: true, status: 'refunded', order_id: rr.order_id, seller_id: rr.seller_id,
+        seller_fault_reason: SELLER_FAULT_REASONS.has(String(rr.reason)) ? String(rr.reason) : null,
+    };
+}
+/**
+ * 直付退货是否可升级争议(escalate 的 direct_p2p 分支;通用分支 rejected / pending≥7d 仍适用):
+ *  - refund_marked:随时可(卖家声明≠买家收到,声明不实的收口权在买家)。
+ *  - await_refund:超 respond 窗(默认 5 天)—— 卖家同意了却迟迟不退款。
+ */
+export function directPayReturnEscalatable(db, rr) {
+    if (rr.status === 'refund_marked')
+        return true;
+    if (rr.status === 'await_refund' && rr.await_refund_since) {
+        const over = db.prepare(`SELECT datetime(?, '+' || ? || ' days') < datetime('now') AS o`)
+            .get(String(rr.await_refund_since), returnRefundRespondDays(db));
+        return !!over.o;
+    }
+    return false;
+}

package/dist/direct-pay-stock.js

@@ -0,0 +1,9 @@
+/** 允许自动回补的取消来源状态(= A 类:货从未出库)。pending_accept=手动接单待确认(v16),付款前必然未出库。 */
+export const PRE_SHIP_RESTOCK_STATUSES = new Set(['pending_accept', 'direct_pay_window', 'direct_expired_unconfirmed', 'payment_query', 'accepted']);
+/** 回补库存(仅 A 类 pre-ship 来源;B 类已出库来源拒绝 —— 走退货验收上架)。返回是否真的回补了。 */
+export function restorePreShipDirectPayStock(db, args) {
+    if (!PRE_SHIP_RESTOCK_STATUSES.has(args.fromStatus))
+        return false; // 已出库/争议来源:绝不直接回补
+    db.prepare('UPDATE products SET stock = stock + ? WHERE id = ?').run(args.quantity, args.productId);
+    return true;
+}

package/dist/direct-receive-account-qr.js

@@ -0,0 +1,77 @@
+import { createHash } from 'crypto';
+export const QR_DATA_URI_RE = /^data:image\/(png|webp);base64,[A-Za-z0-9+/=]+$/;
+export const QR_MAX_BYTES = 64 * 1024;
+/** PNG magic 8 bytes / WEBP RIFF....WEBP。仅接受与声明 mime 一致的字节。 */
+function magicMatches(subtype, buf) {
+    if (subtype === 'png')
+        return buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+    if (subtype === 'webp')
+        return buf.length >= 12 && buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP';
+    return false;
+}
+/** PURE: 校验收款码 data-URI。返回 {ok, ...} 或 {ok:false, reason}。绝不解析二维码。 */
+export function validateQrDataUri(dataUri) {
+    const s = typeof dataUri === 'string' ? dataUri.trim() : '';
+    const m = QR_DATA_URI_RE.exec(s);
+    if (!m)
+        return { ok: false, reason: 'QR must be a data:image/(png|webp);base64 image (svg/html/text/jpeg rejected)' };
+    const subtype = m[1];
+    let buf;
+    try {
+        buf = Buffer.from(s.slice(s.indexOf(',') + 1), 'base64');
+    }
+    catch {
+        return { ok: false, reason: 'QR base64 decode failed' };
+    }
+    if (buf.length === 0)
+        return { ok: false, reason: 'QR is empty' };
+    if (buf.length > QR_MAX_BYTES)
+        return { ok: false, reason: `QR must decode to ≤ ${QR_MAX_BYTES} bytes` };
+    if (!magicMatches(subtype, buf))
+        return { ok: false, reason: `QR bytes do not match declared image/${subtype} (magic-byte mismatch)` };
+    const sha256 = createHash('sha256').update(buf).digest('hex');
+    return { ok: true, value: { mime: `image/${subtype}`, buf, sha256 } };
+}
+/** append-only 审计事件。只记 ref,【绝不】写 raw instruction / raw QR。 */
+export function appendAccountEvent(db, args, generateId) {
+    db.prepare('INSERT INTO direct_receive_account_events (id, account_id, seller_id, event_type, qr_ref) VALUES (?,?,?,?,?)')
+        .run(generateId('drae'), args.accountId, args.sellerId, args.eventType, args.qrRef ?? null);
+}
+/**
+ * 存收款码(owner-scoped)。校验 → sha256 → 【一个同步事务】内:INSERT OR IGNORE 不可变行 + 更新 account.qr_image_ref
+ *   + append qr_uploaded 事件。account 必须属于 sellerId(不属于 → {ok:false})。返回 ref。
+ */
+export function storeQrImage(db, args, generateId) {
+    const v = validateQrDataUri(args.dataUri);
+    if (!v.ok)
+        return v;
+    const owns = db.prepare("SELECT 1 FROM direct_receive_accounts WHERE id = ? AND seller_id = ?").get(args.accountId, args.sellerId);
+    if (!owns)
+        return { ok: false, reason: 'account not found or not owned' };
+    const ref = v.value.sha256;
+    db.transaction(() => {
+        db.prepare('INSERT OR IGNORE INTO direct_receive_account_qr_images (ref, account_id, seller_id, mime, data_b64, byte_len, sha256) VALUES (?,?,?,?,?,?,?)')
+            .run(ref, args.accountId, args.sellerId, v.value.mime, v.value.buf.toString('base64'), v.value.buf.length, ref);
+        db.prepare("UPDATE direct_receive_accounts SET qr_image_ref = ?, updated_at = datetime('now') WHERE id = ? AND seller_id = ?").run(ref, args.accountId, args.sellerId);
+        appendAccountEvent(db, { accountId: args.accountId, sellerId: args.sellerId, eventType: 'qr_uploaded', qrRef: ref }, generateId);
+    })();
+    return { ok: true, ref };
+}
+/** owner-scoped 取码字节(供硬化端点转发)。非本人 / 不存在 → null(端点统一 404,不枚举)。 */
+export function getQrImageForOwner(db, ref, sellerId) {
+    const row = db.prepare('SELECT mime, data_b64 FROM direct_receive_account_qr_images WHERE ref = ? AND seller_id = ?').get(ref, sellerId);
+    if (!row)
+        return null;
+    let buf;
+    try {
+        buf = Buffer.from(row.data_b64, 'base64');
+    }
+    catch {
+        return null;
+    }
+    // defense-in-depth: re-validate on read (mime whitelist + magic + size) — never serve unexpected bytes.
+    const re = validateQrDataUri(`data:${row.mime};base64,${row.data_b64}`);
+    if (!re.ok)
+        return null;
+    return { mime: row.mime, buf };
+}

package/dist/direct-receive-accounts.js

@@ -0,0 +1,82 @@
+export const MAX_INSTRUCTION_LEN = 500;
+export const MAX_LABEL_LEN = 40;
+export const MAX_METHOD_LEN = 40;
+export const MAX_QR_REF_LEN = 200;
+// currency:卖家声明的币种码(自由文本,2-8 位大写字母数字)。WebAZ 不限制卖家怎么收钱;买家侧只在 FX 支持时才显换算。
+export const CURRENCY_RE = /^[A-Z0-9]{2,8}$/;
+/** PURE: 校验 + 规范化卖家入参(trim / 长度 / 币种格式 / 大写)。不碰 DB。
+ *  长度超限 = 【显式拒绝】(非静默截断)—— 卖家看到的收款标签 / 方式 / 二维码引用不能被悄悄改短。 */
+export function normalizeAccountInput(input) {
+    const instruction = String(input?.instruction ?? '').trim();
+    if (!instruction)
+        return { ok: false, reason: 'instruction required' };
+    if (instruction.length > MAX_INSTRUCTION_LEN)
+        return { ok: false, reason: `instruction must be ≤ ${MAX_INSTRUCTION_LEN} chars` };
+    // trim + reject-if-over-limit (no silent slice). null/absent → null.
+    const field = (v, max, name) => {
+        if (v == null)
+            return { ok: true, v: null };
+        const s = String(v).trim();
+        if (s.length > max)
+            return { ok: false, reason: `${name} must be ≤ ${max} chars` };
+        return { ok: true, v: s || null };
+    };
+    const L = field(input.label, MAX_LABEL_LEN, 'label');
+    if (!L.ok)
+        return L;
+    const M = field(input.method, MAX_METHOD_LEN, 'method');
+    if (!M.ok)
+        return M;
+    const Q = field(input.qrImageRef, MAX_QR_REF_LEN, 'qr image ref');
+    if (!Q.ok)
+        return Q;
+    let currency = null;
+    if (input.currency != null && String(input.currency).trim()) {
+        currency = String(input.currency).trim().toUpperCase();
+        if (!CURRENCY_RE.test(currency))
+            return { ok: false, reason: 'currency must be a 2-8 char code (e.g. THB, IDR, USDC)' };
+    }
+    return { ok: true, value: { instruction, label: L.v, method: M.v, currency, qr_image_ref: Q.v } };
+}
+const COLS = 'id, seller_id, method, currency, instruction, label, qr_image_ref, status';
+/** 卖家的收款账号(默认仅 active;{ includeInactive:true } 取全部)。多行。 */
+export function listSellerAccounts(db, sellerId, opts = {}) {
+    const where = opts.includeInactive ? '' : " AND status = 'active'";
+    return db.prepare(`SELECT ${COLS} FROM direct_receive_accounts WHERE seller_id = ?${where} ORDER BY created_at ASC, id ASC`).all(sellerId);
+}
+/** 单个账号(任意状态);调用方自行做 owner 校验。 */
+export function getAccount(db, id) {
+    return db.prepare(`SELECT ${COLS} FROM direct_receive_accounts WHERE id = ?`).get(id) ?? null;
+}
+/** 买家侧【可选收款账号】(仅 active)—— 只投影元数据 method/currency/label 供结算前选"怎么付"+FX 换算展示。
+ *  ⚠️【绝不】含 instruction 原文 / qr_image_ref —— 收款目标受披露门保护(D1/D2 ack 后才随订单快照下发)。 */
+export function listSellerAccountOptions(db, sellerId) {
+    return db.prepare("SELECT id AS account_id, method, currency, label FROM direct_receive_accounts WHERE seller_id = ? AND status = 'active' ORDER BY created_at ASC, id ASC").all(sellerId);
+}
+/** 新增一个 active 收款账号。入参经 normalizeAccountInput 校验;只写本表。 */
+export function addAccount(db, sellerId, input, generateId) {
+    const norm = normalizeAccountInput(input);
+    if (!norm.ok)
+        return norm;
+    const id = generateId('dra');
+    const v = norm.value;
+    db.prepare(`INSERT INTO direct_receive_accounts (id, seller_id, method, currency, instruction, label, qr_image_ref, status) VALUES (?,?,?,?,?,?,?, 'active')`)
+        .run(id, sellerId, v.method, v.currency, v.instruction, v.label, v.qr_image_ref);
+    return { ok: true, account: { id, seller_id: sellerId, status: 'active', ...v } };
+}
+/** owner-scoped 文本字段更新(仅该 seller 拥有的行)。返回是否有行被改。
+ *  ⚠️ 【绝不】碰 qr_image_ref —— 收款码生命周期【只】由 storeQrImage(/qr 端点)管理。
+ *  否则卖家改一次收款说明/标签/币种就会把已上传的 QR 解绑(qr_image_ref→null),核心功能掉链子。 */
+export function updateAccount(db, id, sellerId, input) {
+    const norm = normalizeAccountInput(input);
+    if (!norm.ok)
+        return norm;
+    const v = norm.value;
+    const info = db.prepare(`UPDATE direct_receive_accounts SET method = ?, currency = ?, instruction = ?, label = ?, updated_at = datetime('now') WHERE id = ? AND seller_id = ?`).run(v.method, v.currency, v.instruction, v.label, id, sellerId);
+    return { ok: true, changed: info.changes > 0 };
+}
+/** owner-scoped 软停用。返回是否有行被停用。 */
+export function deactivateAccount(db, id, sellerId) {
+    const info = db.prepare("UPDATE direct_receive_accounts SET status = 'inactive', updated_at = datetime('now') WHERE id = ? AND seller_id = ? AND status = 'active'").run(id, sellerId);
+    return info.changes > 0;
+}