@seasonkoh/webaz 0.1.29 → 0.1.31

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-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-deferral.js

@@ -121,7 +121,36 @@ export function listDeferrals(db, opts = {}) {
     }
     return db.prepare(`SELECT ${cols} FROM direct_receive_deferrals ORDER BY created_at DESC, rowid DESC`).all();
 }
-/** 到期清理(cron):granted 且【超过 grace_until】→ expired。返回受影响的 user_id(调用方据此停权;本模块不改 privileges)。 */
+// ───── B4:缓交收口 —— 到期前提醒 / 缴清转正式 / 到期停权 helper ─────────────────────────────
+/** 即将到期且未提醒过的 granted 缓交(expires_at 在 now..now+withinDays 内)。cron 提醒用;提醒后 markDeferralReminded 去重。 */
+export function listExpiringDeferrals(db, nowIso, withinDays) {
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(now))
+        return [];
+    const rows = db.prepare("SELECT id, user_id, expires_at FROM direct_receive_deferrals WHERE status = 'granted' AND reminder_sent_at IS NULL AND expires_at IS NOT NULL").all();
+    const horizon = now + Math.max(0, withinDays) * 86_400_000;
+    return rows.filter(r => { const e = Date.parse(r.expires_at); return Number.isFinite(e) && e > now && e <= horizon; });
+}
+export function markDeferralReminded(db, deferralId) {
+    db.prepare("UPDATE direct_receive_deferrals SET reminder_sent_at = datetime('now') WHERE id = ? AND reminder_sent_at IS NULL").run(deferralId);
+}
+/** 缴清转正式(B4):生产保证金确认后调用 —— 该 user 的 granted 缓交 → satisfied(解除缓交额度压低;
+ *  入场门此后经 bond 满足)。返回转化条数。 */
+export function satisfyDeferralOnBond(db, userId) {
+    return db.prepare("UPDATE direct_receive_deferrals SET status = 'satisfied', satisfied_at = datetime('now') WHERE user_id = ? AND status = 'granted'").run(userId).changes;
+}
+/** 到期停权(B4):expireDeferrals 的调用方用 —— 该 user 无生产 bond 时把 privilege 置 suspended(理由 deferral_expired)。
+ *  有生产 bond(缓交期间已缴清但 satisfied 漏转的兜底)→ 不停权。 */
+export function suspendPrivilegeOnDeferralExpiry(db, userId) {
+    const hasBond = !!db.prepare("SELECT 1 FROM direct_receive_deposits WHERE user_id = ? AND status = 'locked' AND production_receipt_confirmed_at IS NOT NULL LIMIT 1").get(userId);
+    if (hasBond)
+        return false;
+    db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, suspended_reason, updated_at)
+    VALUES (?, 'suspended', 'T0', 'deferral_expired', datetime('now'))
+    ON CONFLICT(user_id) DO UPDATE SET status='suspended', suspended_reason='deferral_expired', updated_at=datetime('now')`).run(userId);
+    return true;
+}
+/** 到期清理(cron):granted 且【超过 grace_until】→ expired。返回受影响的 user_id(调用方据此停权;本模块不改 privileges —— 停权用 suspendPrivilegeOnDeferralExpiry)。 */
 export function expireDeferrals(db, nowIso) {
     const now = Date.parse(nowIso);
     if (!Number.isFinite(now))

package/dist/direct-receive-deposits.js

@@ -2,13 +2,14 @@ import { toUnits, toDecimal } from './money.js';
 import { getDepositRail, assertProductionDepositRail } from './deposit-rails.js';
 import { assertBondRailCleared } from './direct-pay-bond-rail-clearance.js';
 import { recordBaseBondSlash } from './direct-pay-ledger.js';
+import { getPlatformAccount } from './platform-receive-accounts.js'; // P1:确认时账户快照必须可解析(审计链)
 /** LOCKED 保守默认(治理可调)。T0 = 固定 token 数(标签 ≈ S$500,非 FX)。 */
 export const DEFAULT_BASE_BOND_CONFIG = {
     tierRequiredUnits: { T0: toUnits(500) },
     pendingTtlDays: 7,
 };
 const isNonNegUnits = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
-const getRow = (db, id) => db.prepare('SELECT id, user_id, tier, required_amount, amount, currency, deposit_rail, status, production_receipt_confirmed_at, created_at FROM direct_receive_deposits WHERE id = ?').get(id);
+const getRow = (db, id) => db.prepare('SELECT id, user_id, tier, required_amount, amount, currency, deposit_rail, status, production_receipt_confirmed_at, terms_version, platform_account_id, created_at FROM direct_receive_deposits WHERE id = ?').get(id);
 /** 某档要求的【固定 token 数】(整数 base-units)。未配置的档 → 抛(T1/T2 在 PR-5 才支持)。 */
 export function requiredBondUnits(tier, config = DEFAULT_BASE_BOND_CONFIG) {
     const u = config.tierRequiredUnits[tier];
@@ -36,9 +37,9 @@ export function openDeposit(db, args) {
     catch (e) {
         return { ok: false, reason: e.message };
     }
-    db.prepare(`INSERT INTO direct_receive_deposits (id, user_id, tier, required_amount, amount, currency, deposit_rail, status, created_at, updated_at)
-    VALUES (?,?,?,?,0,?,?, 'pending', datetime('now'), datetime('now'))`)
-        .run(depositId, userId, tier, toDecimal(required), currency, depositRail);
+    db.prepare(`INSERT INTO direct_receive_deposits (id, user_id, tier, required_amount, amount, currency, deposit_rail, status, external_ref, terms_version, platform_account_id, created_at, updated_at)
+    VALUES (?,?,?,?,0,?,?, 'pending', ?, ?, ?, datetime('now'), datetime('now'))`)
+        .run(depositId, userId, tier, toDecimal(required), currency, depositRail, args.externalRef ?? null, args.termsVersion ?? null, args.platformAccountId ?? null);
     return { ok: true, status: 'pending' };
 }
 /**
@@ -153,8 +154,9 @@ export function slashBond(db, args) {
         return { ok: false, reason: 'deposit not found' };
     if (row.status === 'slashed')
         return { ok: true, status: 'slashed', already: true }; // 幂等:不重复记 provenance
-    if (row.status !== 'locked')
-        return { ok: false, reason: `can only slash a locked bond (got '${row.status}')` };
+    // B3:refunding(退出冷静期中)也可罚 —— 退出申请不能成为躲避罚没的通道;罚没即终结退还流。
+    if (row.status !== 'locked' && row.status !== 'refunding')
+        return { ok: false, reason: `can only slash a locked/refunding bond (got '${row.status}')` };
     db.transaction(() => {
         recordBaseBondSlash(db, { userId: row.user_id, amountUnits: toUnits(row.amount), txnId: args.txnId, reason: args.reason }); // provenance only
         db.prepare("UPDATE direct_receive_deposits SET status = 'slashed', updated_at = datetime('now') WHERE id = ?").run(args.depositId);
@@ -166,18 +168,20 @@ export function slashBond(db, args) {
     return { ok: true, status: 'slashed' };
 }
 // ───── PR-4b-3: 生产 receipt 写入(唯一 writer)─────────────────────────────────────────────────
-/** base-bond/合规 policy 版本 —— 【服务端生成】(非客户端入参),legal clearance 落地时随 policy 更新。 */
-export const DIRECT_PAY_BASE_BOND_POLICY_VERSION = 'pre-legal-unset';
-/** 生产 receipt 允许的法域【严格白名单】。默认空 = 任何 jurisdiction 都拒(额外 fail-closed,待法务配置)。 */
-export const DIRECT_PAY_BOND_JURISDICTIONS = [];
+/** base-bond/合规 policy 版本 —— 【服务端生成】(非客户端入参)。2026-07-05 起 = 条款版本(bond-terms.ts,
+ *  缴纳前强制同意;Holden 决策 B 放行 operator_attested,详见 bond-rail-clearance 文件头)。 */
+export const DIRECT_PAY_BASE_BOND_POLICY_VERSION = 'bond-terms.v1.2026-07-05';
+/** 生产 receipt 允许的法域【严格白名单】。语义(P2 澄清):这是【平台收款主体法域】(WebAZ 以哪个法域主体
+ *  接收担保物;决定 registry 放行口径),【不是】卖家法域 —— 卖家侧资格由 KYB/制裁/AML 门独立把守。
+ *  2026-07-05:SG(随 operator_attested 放行)。 */
+export const DIRECT_PAY_BOND_JURISDICTIONS = ['SG'];
 /**
  * 生产保证金 receipt【唯一】writer(PR-4b-3 scaffold)。这是【整个协议中】唯一允许写 production_receipt_confirmed_at
  *   的函数(#100 guard 机器强制:写赋值必在本函数内 且 本函数必调 assertProductionDepositRail)。
  *
- * 当前【fail-closed】:Lock A 对 manual(非生产)/usdc/fiat(GATED,implemented=false)抛;operator_attested 过 Lock A,
- *   但 Lock B(assertBondRailCleared,registry 治理默认关)对所有 rail 抛 → 没有任何 rail 能写 production receipt
- *   → 调用即抛 → 永不写 production receipt → Direct Pay 仍 non-launchable。assert 之后的写路径在 legal-cleared rail
- *   落地前【不可达】(本 PR 不接真实 USDC/fiat/PSP/on-chain)。不碰 buyer wallet/escrow/order/settlement/refund。
+ * 2026-07-05 起:operator_attested 轨已放行(SG;Holden 决策 B,详见 bond-rail-clearance 文件头)→ 本函数
+ *   对该轨【真实可写】(仍要求 ROOT+Passkey 路由门 + 双锁 assert + jurisdiction 白名单)。manual(非生产)与
+ *   usdc/fiat 自动收款轨照旧被 Lock A/B 拒。不碰 buyer wallet/escrow/order/settlement/refund。
  *
  * 硬约束(即便未来 rail 放行也必须守):
  *  - 拒绝把【非生产 locked】(manual/test lock,无 production receipt)升级成生产 —— 旧/测试行不得冒充生产到位。
@@ -186,12 +190,12 @@ export const DIRECT_PAY_BOND_JURISDICTIONS = [];
  */
 export function confirmProductionReceipt(db, args) {
     const { depositId, railId, expectedAmountUnits, receiptRef, jurisdiction } = args;
-    // ⚠️ 生产/法务硬闸 —— assert【真正第一】:在任何 row 读取 / 幂等 / 拒绝 / 写之前。当前所有 rail 都被拒 → 抛 → 恒 fail-closed。
+    // ⚠️ 生产/法务硬闸 —— assert【真正第一】:在任何 row 读取 / 幂等 / 拒绝 / 写之前。未放行 rail 一律抛。
     //   置于最前的语义意义:即便某 deposit 之前在【已 cleared 的 rail】下确认过,若该 rail 后被【撤回】(legalCleared→false),
     //   重新确认也不再被当"幂等已确认"放过 —— 必须重新通过闸。#100 guard 要求本 helper body 必含此调用。
     assertProductionDepositRail(getDepositRail(railId));
     // Lock B(Phase 4 scaffold):rail-clearance registry 放行闸 —— legal_cleared + production_ready + 非占位 policy_version +
-    //   jurisdiction ∈ allowlist。与 Lock A【独立】,缺一即拒;当前 registry 全 fail-closed → 恒抛。置于任何 row 读/写之前。
+    //   jurisdiction ∈ allowlist。与 Lock A【独立】,缺一即拒;置于任何 row 读/写之前。
     assertBondRailCleared(railId, jurisdiction);
     // ───── 以下在 legal-cleared 生产 rail 落地前【全部不可达】(两把闸已抛)─────
     const row = getRow(db, depositId);
@@ -211,6 +215,15 @@ export function confirmProductionReceipt(db, args) {
         return { ok: false, reason: `jurisdiction '${jurisdiction}' not in allowlist` };
     if (!['pending', 'confirmed', 'insufficient'].includes(row.status))
         return { ok: false, reason: `cannot production-confirm from status '${row.status}'` };
+    // P1(#240 审计):生产确认强制【条款同意 + 平台收款账户】—— 没有当前版本条款同意 = 罚没/退还无合同依据;
+    //   没有账户快照 = 收款审计链断。旧申报/绕过 seller route 的 openDeposit 行在此被拒(须重新申报)。
+    if (row.terms_version !== DIRECT_PAY_BASE_BOND_POLICY_VERSION) {
+        return { ok: false, reason: `deposit lacks CURRENT terms agreement (has '${row.terms_version ?? 'none'}', require '${DIRECT_PAY_BASE_BOND_POLICY_VERSION}') — seller must re-declare with terms consent` };
+    }
+    if (!row.platform_account_id)
+        return { ok: false, reason: 'deposit lacks a platform receiving account snapshot — seller must re-declare selecting an account' };
+    if (!getPlatformAccount(db, row.platform_account_id))
+        return { ok: false, reason: `platform account '${row.platform_account_id}' not found — audit chain broken, reject` };
     if (!isNonNegUnits(expectedAmountUnits) || expectedAmountUnits <= 0)
         return { ok: false, reason: 'expectedAmount must be a positive integer base-units' };
     if (expectedAmountUnits < toUnits(row.required_amount))
@@ -239,12 +252,104 @@ export function isProductionBaseBondLocked(db, args) {
 /**
  * 卖家级生产门(PR-4c go-live 充分必要的担保侧条件):该卖家是否有任一【生产级】锁定 base bond
  *   (status='locked' 且 production_receipt_confirmed_at 非 NULL)。**非仅看 direct_receive_privileges.status='active'**。
- * 4b-min 无生产 base-bond rail(WAZ 未启用 / USDC·fiat 生产收款 GATED)→ 恒 false → 直付建单 fail-closed / non-launchable。
+ * 2026-07-05 起 operator_attested 放行 → 经运营确认的保证金使本门为真(直付整体开关 direct_pay.enabled 另判)。
  * 一个生产级 receipt 只会发给已 KYC + 制裁筛查的商户,故该门也承接了 KYC/sanctions(独立 4a 事实门待其系统就绪再接)。
  */
 export function sellerHasProductionBaseBondLocked(db, sellerId) {
     return !!db.prepare("SELECT 1 FROM direct_receive_deposits WHERE user_id = ? AND status = 'locked' AND production_receipt_confirmed_at IS NOT NULL LIMIT 1").get(sellerId);
 }
+/** admin 驳回申报(B1):pending|insufficient|confirmed(未 lock)→ expired + 驳回说明。locked/生产确认后不可驳。幂等。 */
+export function rejectDeposit(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'expired')
+        return { ok: true, status: 'expired', already: true };
+    if (!['pending', 'insufficient', 'confirmed'].includes(row.status))
+        return { ok: false, reason: `cannot reject from status '${row.status}'` };
+    db.prepare(`UPDATE direct_receive_deposits SET status = 'expired', reject_note = ?, updated_at = datetime('now') WHERE id = ?`)
+        .run(args.note ? String(args.note).slice(0, 300) : null, args.depositId);
+    return { ok: true, status: 'expired' };
+}
+// ───── B2:退还(refund-on-exit)状态流。零真实出款 —— 退还动作发生在场外,协议只编排/记录。 ─────
+/** 卖家申请退出退还:locked → refunding(CAS)+ 冷静期锚点 + 暂停直付资格(退出中不得接新直付单)。
+ *  调用方【必须先过 unlock blockers 枚举】(bond-refund-blockers,fail-closed);本函数只做状态手术。 */
+export function requestBondRefund(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row || row.user_id !== args.userId)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status !== 'locked')
+        return { ok: false, reason: `can only request refund on a locked bond (got '${row.status}')` };
+    db.transaction(() => {
+        const r = db.prepare("UPDATE direct_receive_deposits SET status = 'refunding', refund_requested_at = datetime('now'), updated_at = datetime('now') WHERE id = ? AND status = 'locked'").run(args.depositId);
+        if (r.changes !== 1)
+            throw new Error('refund request race: already processed');
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, suspended_reason, updated_at)
+      VALUES (?, 'suspended', ?, 'bond_refund_requested', datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='suspended', suspended_reason='bond_refund_requested', updated_at=datetime('now')`)
+            .run(row.user_id, row.tier);
+    })();
+    return { ok: true, status: 'refunding' };
+}
+/** 卖家撤销退出申请:refunding → locked + 恢复直付资格。仅 admin 尚未执行退还前。 */
+export function cancelBondRefundRequest(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row || row.user_id !== args.userId)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status !== 'refunding')
+        return { ok: false, reason: `no refund request in progress (got '${row.status}')` };
+    db.transaction(() => {
+        const r = db.prepare("UPDATE direct_receive_deposits SET status = 'locked', refund_requested_at = NULL, updated_at = datetime('now') WHERE id = ? AND status = 'refunding'").run(args.depositId);
+        if (r.changes !== 1)
+            throw new Error('cancel race: already processed');
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, suspended_reason, granted_at, updated_at)
+      VALUES (?, 'active', ?, NULL, datetime('now'), datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='active', suspended_reason=NULL, updated_at=datetime('now')`)
+            .run(row.user_id, row.tier);
+    })();
+    return { ok: true, status: 'locked' };
+}
+/** admin 执行退还(场外退款完成后记录):refunding + 冷静期已满 → refunded + 凭据 + released_at。
+ *  资格保持 suspended(bond 已退,入场门 sellerHasProductionBaseBondLocked 自然为 false)。凭据必填。 */
+export function executeBondRefund(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'refunded')
+        return { ok: true, status: 'refunded', already: true };
+    if (row.status !== 'refunding')
+        return { ok: false, reason: `can only execute on a refunding bond (got '${row.status}')` };
+    if (!args.evidenceRef || !args.evidenceRef.trim())
+        return { ok: false, reason: 'refund evidence ref required(场外退还凭据必填)' };
+    const reqAt = db.prepare('SELECT refund_requested_at r FROM direct_receive_deposits WHERE id = ?').get(args.depositId).r;
+    const reqMs = reqAt ? Date.parse(reqAt.includes('T') ? reqAt : reqAt.replace(' ', 'T') + 'Z') : NaN;
+    const nowMs = Date.parse(args.nowIso);
+    const cooling = Math.max(0, args.coolingDays) * 86_400_000;
+    if (!Number.isFinite(reqMs) || !Number.isFinite(nowMs))
+        return { ok: false, reason: 'unparseable refund timestamps' };
+    if (nowMs - reqMs < cooling)
+        return { ok: false, reason: `cooling window not over (need ${args.coolingDays}d from request)` };
+    db.prepare(`UPDATE direct_receive_deposits SET status = 'refunded', released_at = datetime('now'), refund_evidence_ref = ?, updated_at = datetime('now') WHERE id = ? AND status = 'refunding'`)
+        .run(args.evidenceRef.trim().slice(0, 200), args.depositId);
+    return { ok: true, status: 'refunded' };
+}
+/** 卖家自行撤回自己的 pending 申报(B1)。owner-scoped CAS;非 pending 不动。 */
+export function cancelPendingDeposit(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row || row.user_id !== args.userId)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `cannot cancel from status '${row.status}'` };
+    const r = db.prepare("UPDATE direct_receive_deposits SET status = 'expired', reject_note = '卖家自行撤回', updated_at = datetime('now') WHERE id = ? AND user_id = ? AND status = 'pending'")
+        .run(args.depositId, args.userId);
+    return r.changes === 1 ? { ok: true, status: 'expired' } : { ok: false, reason: 'cancel race: already processed' };
+}
+/** 卖家最新一笔保证金存款(任意状态;B1 状态卡/去重用)。 */
+export function getSellerLatestDeposit(db, sellerId) {
+    return db.prepare(`SELECT id, user_id, tier, required_amount, amount, currency, deposit_rail, status, production_receipt_confirmed_at,
+                             external_ref, reject_note, confirmed_at, locked_at, refund_requested_at, refund_evidence_ref, terms_version, platform_account_id, created_at
+                      FROM direct_receive_deposits WHERE user_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(sellerId) ?? null; // rowid=插入序 tiebreak(id 字典序会被混合前缀坑)
+}
 /**
  * refund-on-exit 阻止原因(纯判断占位 —— 真实退款状态流 + RFC-018 clearing lock 集成 = 4b-2)。
  * 返回阻止原因码;null = 在这些条件下【不被阻止】(但本 PR 不执行任何退款)。无副作用,不读库,不出款。

package/dist/free-shipping.js

@@ -0,0 +1,37 @@
+import { toUnits } from './money.js';
+const MAX_THRESHOLD = 10_000_000;
+/** 写入校验:null/空=清除;返回规范化数值或 {error}。 */
+export function validateFreeShippingThreshold(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { value: null };
+    if (typeof raw !== 'number' && typeof raw !== 'string')
+        return { error: '免邮阈值必须是数字' }; // 审计 P3:拒 boolean/数组(Number(true)=1 会误存)
+    const t = Number(raw);
+    if (!Number.isFinite(t) || t <= 0 || t > MAX_THRESHOLD)
+        return { error: `免邮阈值必须是 0~${MAX_THRESHOLD} 的正数` };
+    return { value: Math.round(t * 100) / 100 };
+}
+/** 生效阈值:商品 ?? 店铺 ?? null(与接单/运费/可售同层级约定)。 */
+export function effectiveFreeShippingThreshold(db, product, sellerId) {
+    const own = product.free_shipping_threshold;
+    if (own !== null && own !== undefined && Number.isFinite(Number(own)) && Number(own) > 0)
+        return Number(own);
+    try {
+        const row = db.prepare('SELECT store_free_shipping_threshold FROM users WHERE id = ?').get(sellerId);
+        const st = row?.store_free_shipping_threshold;
+        return (st !== null && st !== undefined && Number.isFinite(Number(st)) && Number(st) > 0) ? Number(st) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 判免:券后货款(整数 units)≥ 生效阈值。读失败 fail-open 到不免(促销缺席≠事故,与合规门相反方向)。 */
+export function freeShippingWaives(db, product, sellerId, goodsSubtotalU) {
+    try {
+        const t = effectiveFreeShippingThreshold(db, product, sellerId);
+        return t !== null && goodsSubtotalU >= toUnits(t);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/fx-rates.js

@@ -67,5 +67,12 @@ export function convertUsdcToLocal(usdcAmount, currency, rates) {
         return NaN;
     return usdcAmount * rate;
 }
+/** SYNC: last-known snapshot(过 TTL 标 stale)或 fallback 表(stale)。给建单时刻的应付参考换算快照用 ——
+ *  display-only,零网络零 await,永不阻塞/永不抛;参考价精度要求低,陈旧可接受且必带 stale 标记。 */
+export function getUsdRatesSync(now = Date.now()) {
+    if (_cache)
+        return now - _cache.fetchedAt < TTL_MS ? _cache.snap : { ...(_cache.snap), stale: true };
+    return { base: 'USD', rates: { ...FALLBACK_USD_RATES }, as_of: new Date(now).toISOString(), stale: true };
+}
 /** test-only: reset the module cache so tests are deterministic. */
 export function __resetFxCacheForTest() { _cache = null; }