@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/direct-receive-deferral.js

@@ -0,0 +1,171 @@
+export const DEFAULT_DEFERRAL_CONFIG = {
+    defaultPeriodDays: 30, defaultGraceDays: 7, minReducedQuotaFactor: 0.1, maxReducedQuotaFactor: 0.9,
+    maxPeriodDays: 365, maxGraceDays: 90,
+};
+const isPosInt = (x) => typeof x === 'number' && Number.isInteger(x) && x > 0;
+const getRow = (db, id) => db.prepare('SELECT id, user_id, status, period_days, reduced_quota_factor, expires_at, grace_until FROM direct_receive_deferrals WHERE id = ?').get(id);
+/** 配额系数夹到 [min,max](不零威慑 + 缓交期必压低);非法/缺省 → 配置默认中点。 */
+export function clampReducedQuotaFactor(factor, config = DEFAULT_DEFERRAL_CONFIG) {
+    const lo = config.minReducedQuotaFactor, hi = config.maxReducedQuotaFactor;
+    const f = typeof factor === 'number' && Number.isFinite(factor) ? factor : (lo + hi) / 2;
+    return Math.min(hi, Math.max(lo, f));
+}
+/** 是否有【活跃】缓交(pending,或 granted 且未过 grace_until)。活跃则禁止再申请。 */
+function hasActiveDeferral(db, userId, nowIso) {
+    const rows = db.prepare("SELECT status, grace_until FROM direct_receive_deferrals WHERE user_id = ? AND status IN ('pending','granted')").all(userId);
+    const now = Date.parse(nowIso);
+    return rows.some(r => r.status === 'pending' || !r.grace_until || !Number.isFinite(Date.parse(r.grace_until)) || Date.parse(r.grace_until) > now);
+}
+/** 申请缓交(商户发起)→ pending。绝不自动授予。 */
+export function requestDeferral(db, args) {
+    const { deferralId, userId, reason, nowIso } = args;
+    const config = args.config ?? DEFAULT_DEFERRAL_CONFIG;
+    if (!deferralId || !userId)
+        return { ok: false, reason: 'missing deferralId/userId' };
+    if (!Number.isFinite(Date.parse(nowIso)))
+        return { ok: false, reason: 'unparseable nowIso' };
+    if (getRow(db, deferralId))
+        return { ok: false, reason: 'deferral id already exists' };
+    const periodDays = args.periodDays ?? config.defaultPeriodDays;
+    if (!isPosInt(periodDays))
+        return { ok: false, reason: 'periodDays must be a positive integer' };
+    // 上限校验:超大 periodDays 会在 approve 时令 new Date(now + days*86_400_000) 溢出 → RangeError(approve 500)。
+    //   在【申请入口】就 fail-closed,既挡 500 也挡超长期缓交。
+    if (periodDays > config.maxPeriodDays)
+        return { ok: false, reason: `periodDays exceeds max (${config.maxPeriodDays})` };
+    if (hasActiveDeferral(db, userId, nowIso))
+        return { ok: false, reason: 'user already has an active deferral' };
+    db.prepare(`INSERT INTO direct_receive_deferrals (id, user_id, reason, period_days, status, created_at)
+    VALUES (?,?,?,?, 'pending', datetime('now'))`).run(deferralId, userId, reason ?? null, periodDays);
+    return { ok: true, status: 'pending' };
+}
+/** 审批通过 → granted。设缓交到期 + 宽限截止 + 压低配额。仅要求 caller 传非空 adminId(无自动批);
+ *  ROOT/Passkey/human-presence 由【调用方 route】强制,helper 不验证身份。 */
+export function approveDeferral(db, args) {
+    const { deferralId, adminId, nowIso } = args;
+    const config = args.config ?? DEFAULT_DEFERRAL_CONFIG;
+    if (!adminId)
+        return { ok: false, reason: 'approveDeferral requires a human adminId (no auto-grant)' };
+    const row = getRow(db, deferralId);
+    if (!row)
+        return { ok: false, reason: 'deferral not found' };
+    if (row.status === 'granted')
+        return { ok: true, status: 'granted', already: true };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `cannot approve from status '${row.status}'` };
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(now))
+        return { ok: false, reason: 'unparseable nowIso' };
+    const graceDays = args.graceDays ?? config.defaultGraceDays;
+    if (!isPosInt(row.period_days) || !(Number.isInteger(graceDays) && graceDays >= 0))
+        return { ok: false, reason: 'invalid period/grace days' };
+    // 上限校验(防溢出 / 超长期):period 是申请时存的(理应已被 requestDeferral 卡住,这里防御 legacy/旁路行),
+    //   grace 是 admin 本次输入。任一超大都会让 new Date(now + (period+grace)*86_400_000) 溢出 → RangeError。
+    //   返回【结构化错误】(由 route 转 409),绝不抛 → 杜绝"消耗 Passkey token 后 500"。
+    if (row.period_days > config.maxPeriodDays)
+        return { ok: false, reason: `periodDays exceeds max (${config.maxPeriodDays})` };
+    if (graceDays > config.maxGraceDays)
+        return { ok: false, reason: `graceDays exceeds max (${config.maxGraceDays})` };
+    const expiresAt = new Date(now + row.period_days * 86_400_000).toISOString().slice(0, 19).replace('T', ' ');
+    const graceUntil = new Date(now + (row.period_days + graceDays) * 86_400_000).toISOString().slice(0, 19).replace('T', ' ');
+    const factor = clampReducedQuotaFactor(args.reducedQuotaFactor, config);
+    db.prepare(`UPDATE direct_receive_deferrals SET status = 'granted', approved_by = ?, approved_at = datetime('now'),
+    expires_at = ?, grace_until = ?, reduced_quota_factor = ? WHERE id = ?`)
+        .run(adminId, expiresAt, graceUntil, factor, deferralId);
+    return { ok: true, status: 'granted' };
+}
+/** 真人 admin 拒绝 → rejected。 */
+export function rejectDeferral(db, args) {
+    if (!args.adminId)
+        return { ok: false, reason: 'rejectDeferral requires a human adminId' };
+    const row = getRow(db, args.deferralId);
+    if (!row)
+        return { ok: false, reason: 'deferral not found' };
+    if (row.status === 'rejected')
+        return { ok: true, status: 'rejected', already: true };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `cannot reject from status '${row.status}'` };
+    db.prepare("UPDATE direct_receive_deferrals SET status = 'rejected', approved_by = ?, approved_at = datetime('now') WHERE id = ?").run(args.adminId, args.deferralId);
+    return { ok: true, status: 'rejected' };
+}
+/**
+ * 取某 user 当前【生效中】的缓交(granted 且 now ≤ grace_until)。无 → null。供 PR2 eligibility / 配额读取。
+ * 【FAIL-CLOSED】:grace_until 或 expires_at 为空/不可解析 = 坏 granted 行,**绝不**当作 active(返回 null 跳过)。
+ *   语义与 expireDeferrals 一致(坏行视为可清理/不生效),杜绝"坏 granted 行被误认有效缓交"放进 eligibility。
+ */
+export function getActiveDeferral(db, userId, nowIso) {
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(now))
+        return null;
+    const rows = db.prepare("SELECT id, reduced_quota_factor, expires_at, grace_until FROM direct_receive_deferrals WHERE user_id = ? AND status = 'granted'").all(userId);
+    for (const r of rows) {
+        const grace = r.grace_until ? Date.parse(r.grace_until) : NaN;
+        const exp = r.expires_at ? Date.parse(r.expires_at) : NaN;
+        // fail-closed:两个时钟锚点都必须是合法时间;grace 必须在未来。任一空/坏 → 跳过(不承认为 active)。
+        if (Number.isFinite(grace) && Number.isFinite(exp) && grace > now) {
+            return { id: r.id, reducedQuotaFactor: r.reduced_quota_factor, expiresAt: r.expires_at, graceUntil: r.grace_until, inGrace: now > exp };
+        }
+    }
+    return null;
+}
+/** 取某 user【最新一条】缓交申请(任意状态)。无 → null。纯读。供卖家自助 status 端点展示当前申请状态。 */
+export function getLatestDeferral(db, userId) {
+    // created_at 同秒并列时用 rowid(插入序)兜底,保证"最新"=最后插入,确定性。
+    return db.prepare(`SELECT id, status, period_days, reduced_quota_factor, expires_at, grace_until, created_at
+    FROM direct_receive_deferrals WHERE user_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(userId) ?? null;
+}
+export function listDeferrals(db, opts = {}) {
+    const cols = 'id, user_id, reason, period_days, reduced_quota_factor, status, approved_by, approved_at, expires_at, grace_until, created_at';
+    if (opts.status) {
+        return db.prepare(`SELECT ${cols} FROM direct_receive_deferrals WHERE status = ? ORDER BY created_at DESC, rowid DESC`).all(opts.status);
+    }
+    return db.prepare(`SELECT ${cols} FROM direct_receive_deferrals ORDER BY created_at DESC, rowid DESC`).all();
+}
+// ───── 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))
+        return { expired: [] };
+    const rows = db.prepare("SELECT id, user_id, grace_until FROM direct_receive_deferrals WHERE status = 'granted'").all();
+    const expired = [];
+    const tx = db.transaction(() => {
+        for (const r of rows) {
+            const grace = r.grace_until ? Date.parse(r.grace_until) : NaN;
+            if (!Number.isFinite(grace) || grace <= now) {
+                db.prepare("UPDATE direct_receive_deferrals SET status = 'expired' WHERE id = ?").run(r.id);
+                expired.push(r.user_id);
+            }
+        }
+    });
+    tx();
+    return { expired };
+}

package/dist/direct-receive-deposits.js

@@ -0,0 +1,365 @@
+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, 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];
+    if (!isNonNegUnits(u) || u <= 0)
+        throw new Error(`requiredBondUnits: tier '${tier}' 未配置或非正整数 units(4b-min 仅支持已配置档,通常 T0)`);
+    return u;
+}
+/** 开新存款:创建 pending 行。required = 该档固定 token 数。amount=0(待 confirm)。 */
+export function openDeposit(db, args) {
+    const { depositId, userId, tier, currency, depositRail, config } = args;
+    if (!depositId || !userId)
+        return { ok: false, reason: 'missing depositId/userId' };
+    // WAZ NOT enabled:base bond 只接受【外部资产币种】usdc | fiat(生产收款仍 GATED);'waz' 一律 fail-closed,
+    //   杜绝把 schema 默认 currency='waz' 固化成合法路径(防 4c/4f 误接成"WAZ 担保物可用")。
+    if (!['usdc', 'fiat'].includes(currency))
+        return { ok: false, reason: `currency '${currency}' not allowed for base bond (only usdc|fiat; WAZ not enabled)` };
+    if (!['manual', 'operator_attested', 'usdc_onchain', 'fiat_psp'].includes(depositRail))
+        return { ok: false, reason: `invalid deposit_rail '${depositRail}'` };
+    if (getRow(db, depositId))
+        return { ok: false, reason: 'deposit already exists' };
+    let required;
+    try {
+        required = requiredBondUnits(tier, config);
+    }
+    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, 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' };
+}
+/**
+ * 确认到账(经 deposit-rail 网关)。
+ *  - manual rail:仅 test/non-production —— 置 amount + status=confirmed,**绝不**设 production_receipt_confirmed_at。
+ *  - usdc_onchain / fiat_psp:getDepositRail().confirmReceipt() 直接【抛】(GATED,fail-closed),本函数不吞。
+ * production_receipt_confirmed_at 只由【未来的 legal-cleared 生产 rail】设置(当前不存在)→ 本 PR 后恒 NULL。
+ */
+export function confirmDepositReceipt(db, args) {
+    const { depositId, expectedAmountUnits, externalRef } = args;
+    const row = getRow(db, depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    // 生产 rail(operator_attested / usdc_onchain / fiat_psp)只能走 confirmProductionReceipt(ROOT + Passkey + Lock B)。
+    //   confirmDepositReceipt 是【非生产 / manual 专用】路径 —— 任何生产 rail 在此即抛(fail-closed),杜绝被
+    //   confirmDepositReceipt + lockBond 锁成 active privilege、绕过生产确认门(operator_attested 的 record-only
+    //   confirmReceipt 不会自己抛,故必须在此显式拦)。
+    if (getDepositRail(row.deposit_rail).isProduction) {
+        throw new Error(`deposit-rail '${row.deposit_rail}' is a production rail — must use confirmProductionReceipt (ROOT + Passkey); confirmDepositReceipt is manual/non-production only`);
+    }
+    if (row.status === 'confirmed' || row.status === 'locked')
+        return { ok: true, status: row.status, already: true }; // 幂等
+    if (row.status !== 'pending' && row.status !== 'insufficient')
+        return { ok: false, reason: `cannot confirm from status '${row.status}'` };
+    if (!isNonNegUnits(expectedAmountUnits) || expectedAmountUnits <= 0)
+        return { ok: false, reason: 'expectedAmount must be a positive integer base-units' };
+    // 网关:manual → confirmed(test);usdc/fiat → 抛(GATED)。本函数不 try/catch 网关,让 GATED 抛穿透(fail-closed)。
+    const conf = getDepositRail(row.deposit_rail)
+        .confirmReceipt({ depositId, expectedAmount: expectedAmountUnits, currency: row.currency, externalRef });
+    if (!conf.confirmed)
+        return { ok: false, reason: conf.reason || 'receipt not confirmed' };
+    // manual = 非生产 → 绝不写 production_receipt_confirmed_at(保持 NULL)。
+    db.prepare(`UPDATE direct_receive_deposits SET amount = ?, status = 'confirmed', confirmed_at = datetime('now'),
+    external_ref = COALESCE(?, external_ref), updated_at = datetime('now') WHERE id = ?`)
+        .run(toDecimal(expectedAmountUnits), conf.externalRef ?? externalRef ?? null, depositId);
+    return { ok: true, status: 'confirmed' };
+}
+/** 锁定:confirmed 且 amount ≥ required → locked + 激活 privilege(单事务)。WAZ NOT enabled → 不动任何余额。 */
+export function lockBond(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'locked')
+        return { ok: true, status: 'locked', already: true }; // 幂等
+    if (row.status !== 'confirmed')
+        return { ok: false, reason: `cannot lock from status '${row.status}' (must be confirmed)` };
+    if (toUnits(row.amount) < toUnits(row.required_amount))
+        return { ok: false, reason: 'insufficient: amount < required' };
+    db.transaction(() => {
+        db.prepare("UPDATE direct_receive_deposits SET status = 'locked', locked_at = datetime('now'), updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+        // ⚠️ privilege=active 在 4b-min 是【非生产】(manual/test;本 PR 的 lock 不带 production_receipt_confirmed_at)。
+        //   active 本身【不是】production go-live 的充分条件 —— 生产门是 isProductionBaseBondLocked()(production receipt 非 NULL),
+        //   由 4c 强制;active 仅表示"已走完非生产 lock 流程"。
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, granted_at, updated_at)
+      VALUES (?, 'active', ?, datetime('now'), datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='active', tier=excluded.tier, suspended_reason=NULL, granted_at=COALESCE(direct_receive_privileges.granted_at, excluded.granted_at), updated_at=datetime('now')`)
+            .run(row.user_id, row.tier);
+    })();
+    return { ok: true, status: 'locked' };
+}
+/** 标记不足:confirmed 但 amount < required → insufficient(待 top-up)。 */
+export function markInsufficient(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'insufficient')
+        return { ok: true, status: 'insufficient', already: true };
+    if (row.status !== 'confirmed')
+        return { ok: false, reason: `cannot mark insufficient from status '${row.status}'` };
+    if (toUnits(row.amount) >= toUnits(row.required_amount))
+        return { ok: false, reason: 'amount already meets required' };
+    db.prepare("UPDATE direct_receive_deposits SET status = 'insufficient', updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+    return { ok: true, status: 'insufficient' };
+}
+/** 补足:amount += add(整数 units)。若达/超 required 且当前 insufficient/confirmed → 置 confirmed(可再 lock)。 */
+export function topUp(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (!isNonNegUnits(args.addUnits) || args.addUnits <= 0)
+        return { ok: false, reason: 'addUnits must be a positive integer base-units' };
+    if (!['confirmed', 'insufficient'].includes(row.status))
+        return { ok: false, reason: `cannot top-up from status '${row.status}'` };
+    const newAmount = toUnits(row.amount) + args.addUnits;
+    db.prepare("UPDATE direct_receive_deposits SET amount = ?, status = 'confirmed', updated_at = datetime('now') WHERE id = ?")
+        .run(toDecimal(newAmount), args.depositId);
+    return { ok: true, status: 'confirmed' };
+}
+/** 过期:pending 且超过 TTL → expired。 */
+export function expireDeposit(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `only pending can expire (got '${row.status}')` };
+    const ttlDays = args.config?.pendingTtlDays ?? DEFAULT_BASE_BOND_CONFIG.pendingTtlDays;
+    const created = Date.parse(row.created_at), now = Date.parse(args.nowIso);
+    if (!Number.isFinite(created) || !Number.isFinite(now))
+        return { ok: false, reason: 'unparseable timestamps' };
+    if (now - created < ttlDays * 86_400_000)
+        return { ok: false, reason: 'not yet past TTL' };
+    db.prepare("UPDATE direct_receive_deposits SET status = 'expired', updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+    return { ok: true, status: 'expired' };
+}
+/**
+ * 罚没(卖家违约):locked → slashed,仅记 provenance(recordBaseBondSlash:total_base_bond_slash + txn),
+ *  **不动任何 balance / 无 outflow**(WAZ NOT enabled),并吊销 privilege(suspended)。单事务,幂等。
+ */
+export function slashBond(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'slashed')
+        return { ok: true, status: 'slashed', already: true }; // 幂等:不重复记 provenance
+    // 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);
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, suspended_reason, updated_at)
+      VALUES (?, 'suspended', ?, ?, datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='suspended', suspended_reason=excluded.suspended_reason, updated_at=datetime('now')`)
+            .run(row.user_id, row.tier, args.reason ?? 'base_bond_slashed');
+    })();
+    return { ok: true, status: 'slashed' };
+}
+// ───── PR-4b-3: 生产 receipt 写入(唯一 writer)─────────────────────────────────────────────────
+/** 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)。
+ *
+ * 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)升级成生产 —— 旧/测试行不得冒充生产到位。
+ *  - jurisdiction 必须 ∈ DIRECT_PAY_BOND_JURISDICTIONS(严格白名单);policy_version 由服务端常量盖章,非入参。
+ *  - assert 在任何写之前;原子 confirm+lock(amount + status=locked + production receipt + provenance 快照 + privilege)。
+ */
+export function confirmProductionReceipt(db, args) {
+    const { depositId, railId, expectedAmountUnits, receiptRef, jurisdiction } = args;
+    // ⚠️ 生产/法务硬闸 —— 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【独立】,缺一即拒;置于任何 row 读/写之前。
+    assertBondRailCleared(railId, jurisdiction);
+    // ───── 以下在 legal-cleared 生产 rail 落地前【全部不可达】(两把闸已抛)─────
+    const row = getRow(db, depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (railId !== row.deposit_rail)
+        return { ok: false, reason: 'rail_id does not match the deposit rail' };
+    // 幂等:已生产确认 → already(此时 rail 仍 cleared,assert 已过)
+    if (row.status === 'locked' && row.production_receipt_confirmed_at != null)
+        return { ok: true, status: 'locked', already: true };
+    // 拒绝把【非生产 locked】(manual/test lock,无 production receipt)升级成生产
+    if (row.status === 'locked')
+        return { ok: false, reason: 'deposit is locked WITHOUT a production receipt (manual/test) — cannot be upgraded to production' };
+    if (!receiptRef)
+        return { ok: false, reason: 'missing production receipt ref' };
+    if (!DIRECT_PAY_BOND_JURISDICTIONS.includes(jurisdiction))
+        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))
+        return { ok: false, reason: 'insufficient: amount < required' };
+    db.transaction(() => {
+        db.prepare(`UPDATE direct_receive_deposits SET amount = ?, status = 'locked', confirmed_at = COALESCE(confirmed_at, datetime('now')),
+      locked_at = datetime('now'), production_receipt_confirmed_at = datetime('now'),
+      production_receipt_ref = ?, production_rail_id = ?, production_jurisdiction = ?, production_policy_version = ?,
+      external_ref = COALESCE(?, external_ref), updated_at = datetime('now') WHERE id = ?`)
+            .run(toDecimal(expectedAmountUnits), receiptRef, railId, jurisdiction, DIRECT_PAY_BASE_BOND_POLICY_VERSION, receiptRef, depositId);
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, granted_at, updated_at)
+      VALUES (?, 'active', ?, datetime('now'), datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='active', tier=excluded.tier, suspended_reason=NULL, granted_at=COALESCE(direct_receive_privileges.granted_at, excluded.granted_at), updated_at=datetime('now')`)
+            .run(row.user_id, row.tier);
+    })();
+    return { ok: true, status: 'locked' };
+}
+/**
+ * 生产门读取:某存款是否【生产级】锁定 = status='locked' 且 production_receipt_confirmed_at 非 NULL。
+ * 4b-min 永远 false(manual rail 不设该列;无生产 rail)。供后续 4c 生产 go-live 事实装配【单一真相】,杜绝 manual 冒充。
+ */
+export function isProductionBaseBondLocked(db, args) {
+    const row = getRow(db, args.depositId);
+    return !!row && row.status === 'locked' && row.production_receipt_confirmed_at != null;
+}
+/**
+ * 卖家级生产门(PR-4c go-live 充分必要的担保侧条件):该卖家是否有任一【生产级】锁定 base bond
+ *   (status='locked' 且 production_receipt_confirmed_at 非 NULL)。**非仅看 direct_receive_privileges.status='active'**。
+ * 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 不执行任何退款)。无副作用,不读库,不出款。
+ */
+export function refundOnExitBlockedReason(facts) {
+    if (facts.status !== 'locked')
+        return 'NOT_LOCKED';
+    if (facts.hasOpenDispute === true)
+        return 'OPEN_DISPUTE';
+    if (facts.withinCoolingWindow === true)
+        return 'COOLING_WINDOW';
+    return null;
+}

package/dist/direct-receive-payment-instruction.js

@@ -0,0 +1,26 @@
+/** instruction / label 文本上限(纯展示文本,防滥用;非业务语义)。 */
+export const MAX_INSTRUCTION_LEN = 500;
+export const MAX_LABEL_LEN = 40;
+/** 卖家当前 active 收款说明(最新一条)。无则 null → 调用方必须 fail-closed,不创建直付订单。 */
+export function getActivePaymentInstruction(db, sellerId) {
+    const r = db.prepare("SELECT id, instruction, label FROM direct_receive_payment_instructions WHERE seller_id = ? AND status = 'active' ORDER BY updated_at DESC, created_at DESC LIMIT 1").get(sellerId);
+    return r ?? null;
+}
+/**
+ * 设置/替换卖家当前 active 收款说明。原子:同一同步事务内先把该 seller 所有 active 置 inactive,再插入一条新 active。
+ *   保证至多一条 active。instruction/label 调用方需先 trim + 校验非空/长度;此处只信任已校验入参并落库。
+ *   只写 direct_receive_payment_instructions,绝不碰 wallet/escrow/settlement/order。
+ */
+export function setActivePaymentInstruction(db, sellerId, args, generateId) {
+    const id = generateId('dri');
+    db.transaction(() => {
+        db.prepare("UPDATE direct_receive_payment_instructions SET status = 'inactive', updated_at = datetime('now') WHERE seller_id = ? AND status = 'active'").run(sellerId);
+        db.prepare("INSERT INTO direct_receive_payment_instructions (id, seller_id, instruction, label, status) VALUES (?, ?, ?, ?, 'active')").run(id, sellerId, args.instruction, args.label);
+    })();
+    return { id, instruction: args.instruction, label: args.label };
+}
+/** 停用卖家当前所有 active 收款说明。返回是否有行被停用(false = 本来就没有 active)。 */
+export function deactivatePaymentInstruction(db, sellerId) {
+    const info = db.prepare("UPDATE direct_receive_payment_instructions SET status = 'inactive', updated_at = datetime('now') WHERE seller_id = ? AND status = 'active'").run(sellerId);
+    return info.changes > 0;
+}

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;
+    }
+}