@seasonkoh/webaz 0.1.28 → 0.1.30

package/README.md

@@ -50,8 +50,9 @@ WebAZ ships an **MCP server**. MCP is an open standard, so it works with **any M
 { "mcpServers": { "webaz": { "command": "npx", "args": ["-y", "@seasonkoh/webaz"] } } }
 ```
 
-- 🟡 **Sandbox (default, zero-config):** with no `WEBAZ_API_KEY`, the agent runs against a **private local SQLite playground, isolated from the live network** — safe to try `webaz_register` / `webaz_search` / the whole order flow.
-- 🟢 **Network:** register at [webaz.xyz](https://webaz.xyz) (invite + Passkey = an accountable human), copy your `api_key`, and set it as `env.WEBAZ_API_KEY` → the agent acts on the **live shared network**. (On Network, `webaz_register` never self-creates an account — accounts require a real human + Passkey, by protocol.)
+- 🟢 **Network read-only (default, zero-config):** with no `WEBAZ_API_KEY`, public reads (`webaz_search` / leaderboard / price history / browse) hit the **live shared network** at [webaz.xyz](https://webaz.xyz) — nothing local. Transactional tools (register / order / list / fulfill) need a key.
+- 🟢 **Network (full):** register at [webaz.xyz](https://webaz.xyz) (invite + Passkey = an accountable human), copy your `api_key`, and set it as `env.WEBAZ_API_KEY` → the agent can transact on the **live shared network**. (`webaz_register` never self-creates an account — accounts require a real human + Passkey, by protocol.)
+- 🟡 **Sandbox (explicit, dev/demo):** set `WEBAZ_MODE=sandbox` → a **private local SQLite playground, isolated from the live network** — safe to try the whole order flow offline. (Opt-in; the default with no key is Network read-only, not sandbox.)
 
 Every tool result is stamped with `_mode` so the agent always knows which network it's on. There are **38 tools**; ask `webaz_info` for the live list and params. A first prompt to try:
 

package/README.zh-CN.md

@@ -94,16 +94,17 @@
 
 ### 方式一：MCP 接入（任意 agent —— agent 原生体验）
 
-MCP server 有两种模式 / The MCP runs in one of two modes：
+MCP server 有三种模式 / The MCP runs in one of three modes：
 
 | 模式 / Mode | 数据源 | 用途 | 如何触发 |
 |---|---|---|---|
-| 🟢 **NETWORK** | `webaz.xyz` 共享生产网络（带你的 `api_key`） | 真实加入网络、和别人交易 | 配了 `WEBAZ_API_KEY` |
-| 🟡 **SANDBOX** | 本机本地 SQLite（`~/.webaz/webaz.db`） | 离线试玩 / 开发，**与全网隔离** | 未配 `WEBAZ_API_KEY`（默认） |
+| 🟢 **NETWORK 只读（默认）** | `webaz.xyz` 共享生产网络（公共读） | 无需 key 即可搜索 / 榜单 / 价格史 / 浏览**真实网络** | 未配 `WEBAZ_API_KEY`（默认，零配置） |
+| 🟢 **NETWORK（完整）** | `webaz.xyz` 共享生产网络（带你的 `api_key`） | 真实加入网络、和别人交易 | 配了 `WEBAZ_API_KEY` |
+| 🟡 **SANDBOX** | 本机本地 SQLite（`~/.webaz/webaz.db`） | 离线试玩 / 开发，**与全网隔离** | **显式** `WEBAZ_MODE=sandbox` |
 
-> 🟢 NETWORK = your agent acts on the live shared network. 🟡 SANDBOX = local-only, private to your machine, **not** the live network. Every tool result is stamped with `_mode` so you always know which one you're in.
+> 🟢 无 key = 公共读打**真网络**（不是本机）；要交易（注册/下单/上架/履约）需 `WEBAZ_API_KEY`。🟡 SANDBOX 需**显式开启**（`WEBAZ_MODE=sandbox`），本机隔离，**不是**真网络。每个工具结果都盖 `_mode`，一眼知道当前在哪。
 
-**A. 先离线试玩（SANDBOX，零配置）**
+**A. 零配置开始（NETWORK 只读）**
 
 把下面的 server 配置加进**你的 MCP 客户端**——以 Claude Desktop 为例,编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`(Claude Code 用 `claude mcp add`;Codex / Cursor / 其它 MCP 客户端用各自的 MCP 配置文件,字段相同):
 
@@ -118,7 +119,7 @@ MCP server 有两种模式 / The MCP runs in one of two modes：
 }
 ```
 
-重启你的 MCP 客户端。`npx` 自动下载运行。此时所有数据都在本机沙盒，可放心试 `webaz_register` / `webaz_search` / 下单全流程。
+重启你的 MCP 客户端。`npx` 自动下载运行。**无 key 时是 NETWORK 只读**：`webaz_search` / 榜单 / 价格史 / 浏览直接读 `webaz.xyz` 真实网络（注册 / 下单 / 上架等交易工具需要 key，见 B）。想完全离线试玩全流程？设 `WEBAZ_MODE=sandbox` 进本机沙盒（仅本机有效，与全网隔离）。
 
 **B. 真正加入网络（NETWORK）**
 

package/dist/bond-refund-blockers.js

@@ -0,0 +1,50 @@
+import { OPEN_FEE_ACCRUING_STATUSES, readAvailableFeePrepayUnits } from './direct-pay-fee-ar.js';
+import { sellerHasPendingSlash } from './bond-slash.js'; // B3:待复核罚没提案挡退出
+export function enumerateBondRefundBlockers(db, sellerId) {
+    const out = [];
+    // ① 在途直付单(OPEN_FEE_ACCRUING_STATUSES 已含 pending_accept..disputed 全部非终态)
+    try {
+        const ph = OPEN_FEE_ACCRUING_STATUSES.map(() => '?').join(',');
+        const n = db.prepare(`SELECT COUNT(*) n FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND status IN (${ph})`)
+            .get(sellerId, ...OPEN_FEE_ACCRUING_STATUSES).n;
+        if (n > 0)
+            out.push({ code: 'OPEN_DIRECT_PAY_ORDERS', count: n });
+    }
+    catch {
+        out.push({ code: 'UNVERIFIABLE_OPEN_ORDERS' });
+    }
+    // ② 取消退款握手进行中(防御性)
+    try {
+        const n = db.prepare(`SELECT COUNT(*) n FROM direct_pay_cancel_requests WHERE seller_id = ? AND status IN ('requested','refund_marked')`)
+            .get(sellerId).n;
+        if (n > 0)
+            out.push({ code: 'OPEN_CANCEL_REFUND_HANDSHAKE', count: n });
+    }
+    catch {
+        out.push({ code: 'UNVERIFIABLE_CANCEL_REFUND' });
+    }
+    // ③ 退货流进行中(completed 直付单的退货/场外退款握手 —— ① 覆盖不到)
+    try {
+        const n = db.prepare(`SELECT COUNT(*) n FROM return_requests r JOIN orders o ON o.id = r.order_id
+      WHERE o.seller_id = ? AND o.payment_rail = 'direct_p2p'
+        AND r.status IN ('pending','accepted_pickup_pending','picked_up','await_refund','refund_marked')`)
+            .get(sellerId).n;
+        if (n > 0)
+            out.push({ code: 'OPEN_RETURN_FLOW', count: n });
+    }
+    catch {
+        out.push({ code: 'UNVERIFIABLE_RETURNS' });
+    }
+    // ⑤ 待复核罚没提案(B3;sellerHasPendingSlash 内部 fail-closed)
+    if (sellerHasPendingSlash(db, sellerId))
+        out.push({ code: 'PENDING_SLASH_REVIEW' });
+    // ④ 平台服务费欠费(available = Σ预充值 + Σ调整 − Σ已计提;负 = 欠)
+    try {
+        if (readAvailableFeePrepayUnits(db, sellerId) < 0)
+            out.push({ code: 'UNPAID_PLATFORM_FEES' });
+    }
+    catch {
+        out.push({ code: 'UNVERIFIABLE_FEES' });
+    }
+    return out;
+}

package/dist/bond-slash.js

@@ -0,0 +1,100 @@
+import { slashBond } from './direct-receive-deposits.js';
+const SELLER_FAULT_RULINGS = ['refund_buyer', 'partial_refund'];
+/** 卖家是否有待复核罚没提案(B2 退出 blockers 用)。 */
+export function sellerHasPendingSlash(db, sellerId) {
+    try {
+        return !!db.prepare("SELECT 1 FROM bond_slash_proposals WHERE seller_id = ? AND status = 'proposed' LIMIT 1").get(sellerId);
+    }
+    catch {
+        return true;
+    } // 表读不了 → fail-closed(视为有,挡退出)
+}
+/** admin 发起罚没提案。校验依据争议 + deposit 状态;冷静期算成绝对截止存库。 */
+export function proposeBondSlash(db, args) {
+    const dep = db.prepare('SELECT id, user_id, status, production_receipt_confirmed_at FROM direct_receive_deposits WHERE id = ?')
+        .get(args.depositId);
+    if (!dep)
+        return { ok: false, reason: 'deposit not found' };
+    if (dep.status !== 'locked' && dep.status !== 'refunding')
+        return { ok: false, reason: `can only propose slash on a locked/refunding bond (got '${dep.status}')` };
+    const dsp = db.prepare(`SELECT d.id, d.status, d.ruling_type, o.payment_rail, o.seller_id
+                          FROM disputes d JOIN orders o ON o.id = d.order_id WHERE d.id = ?`)
+        .get(args.disputeId);
+    if (!dsp)
+        return { ok: false, reason: 'dispute not found' };
+    if (dsp.payment_rail !== 'direct_p2p')
+        return { ok: false, reason: 'dispute is not on a direct_p2p order(罚没口径仅直付争议)' };
+    if (dsp.seller_id !== dep.user_id)
+        return { ok: false, reason: 'dispute seller does not match bond owner' };
+    if (dsp.status !== 'resolved' || !dsp.ruling_type || !SELLER_FAULT_RULINGS.includes(dsp.ruling_type)) {
+        return { ok: false, reason: `dispute must be resolved with a seller-fault ruling (${SELLER_FAULT_RULINGS.join('|')}); got status='${dsp.status}' ruling='${dsp.ruling_type ?? 'none'}'` };
+    }
+    const open = db.prepare("SELECT 1 FROM bond_slash_proposals WHERE deposit_id = ? AND status = 'proposed' LIMIT 1").get(args.depositId);
+    if (open)
+        return { ok: false, reason: 'an open slash proposal already exists for this deposit' };
+    const days = Math.max(0, args.coolingDays);
+    db.prepare(`INSERT INTO bond_slash_proposals (id, deposit_id, seller_id, dispute_id, reason, status, cooling_until, proposed_by)
+              VALUES (?,?,?,?,?, 'proposed', datetime('now', ?), ?)`)
+        .run(args.proposalId, args.depositId, dep.user_id, args.disputeId, args.reason ? String(args.reason).slice(0, 300) : null, `+${days} days`, args.proposedBy);
+    return { ok: true, proposalId: args.proposalId, status: 'proposed' };
+}
+/** admin 撤销提案(执行前任意时刻)。 */
+export function cancelBondSlashProposal(db, args) {
+    const row = db.prepare('SELECT status FROM bond_slash_proposals WHERE id = ?').get(args.proposalId);
+    if (!row)
+        return { ok: false, reason: 'proposal not found' };
+    if (row.status === 'cancelled')
+        return { ok: true, status: 'cancelled', already: true };
+    if (row.status !== 'proposed')
+        return { ok: false, reason: `cannot cancel from status '${row.status}'` };
+    db.prepare("UPDATE bond_slash_proposals SET status = 'cancelled', cancelled_at = datetime('now'), cancel_note = ? WHERE id = ? AND status = 'proposed'")
+        .run(args.note ? String(args.note).slice(0, 300) : null, args.proposalId);
+    return { ok: true, status: 'cancelled' };
+}
+/**
+ * 执行罚没:提案 proposed + 冷静期已过 → 同一事务内 CAS(proposed→executed)+ slashBond(全额 provenance
+ * + status slashed + 资格吊销)。txnId 由调用方生成(审计关联)。
+ */
+export function executeBondSlashProposal(db, args) {
+    const row = db.prepare('SELECT id, deposit_id, seller_id, dispute_id, reason, status, cooling_until FROM bond_slash_proposals WHERE id = ?')
+        .get(args.proposalId);
+    if (!row)
+        return { ok: false, reason: 'proposal not found' };
+    if (row.status === 'executed')
+        return { ok: true, status: 'executed', already: true };
+    if (row.status !== 'proposed')
+        return { ok: false, reason: `cannot execute from status '${row.status}'` };
+    const coolMs = Date.parse(row.cooling_until.includes('T') ? row.cooling_until : row.cooling_until.replace(' ', 'T') + 'Z');
+    const nowMs = Date.parse(args.nowIso);
+    if (!Number.isFinite(coolMs) || !Number.isFinite(nowMs))
+        return { ok: false, reason: 'unparseable cooling timestamps' };
+    if (nowMs < coolMs)
+        return { ok: false, reason: `cooling window not over (until ${row.cooling_until})` };
+    let out = { ok: true, status: 'executed' };
+    db.transaction(() => {
+        const cas = db.prepare("UPDATE bond_slash_proposals SET status = 'executed', executed_at = datetime('now'), executed_txn_id = ? WHERE id = ? AND status = 'proposed'")
+            .run(args.txnId, args.proposalId);
+        if (cas.changes !== 1)
+            throw new Error('execute race: already processed');
+        const s = slashBond(db, { depositId: row.deposit_id, txnId: args.txnId, reason: `bond_slash_proposal:${row.id} dispute:${row.dispute_id}${row.reason ? ` ${row.reason}` : ''}` });
+        if (!s.ok)
+            throw new Error(s.reason);
+    })();
+    return out;
+}
+/** 提案列表(admin 队列/卖家告知)。 */
+export function listBondSlashProposals(db, filter = {}) {
+    const where = [];
+    const params = [];
+    if (filter.sellerId) {
+        where.push('p.seller_id = ?');
+        params.push(filter.sellerId);
+    }
+    if (filter.status) {
+        where.push('p.status = ?');
+        params.push(filter.status);
+    }
+    return db.prepare(`SELECT p.*, u.name AS seller_name, u.handle AS seller_handle
+                     FROM bond_slash_proposals p JOIN users u ON u.id = p.seller_id
+                     ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY p.proposed_at DESC LIMIT 200`).all(...params);
+}

package/dist/bond-terms.js

@@ -0,0 +1,31 @@
+/**
+ * 商家履约保证金条款(B 决策前置,2026-07-05)。
+ *
+ * 为什么存在:罚没/退还必须有【商家缴纳前显式同意】的合同依据 —— 没有条款文本,罚没在合同法上站不住
+ *   (SG 语境:罚没条款须像"约定履约损害赔偿"而非"惩罚",penalty clause 可能不可执行,故文本刻意
+ *   采用 liquidated-damages 表述并写明用途去向)。条款版本化:缴纳申报时快照 terms_version 进 deposit 行,
+ *   新版本只影响之后的缴纳;版本串同时作为 rail-clearance 的 policy_version(可审计对齐)。
+ *
+ * 变更本文本 = 变更商家合同条款:必须 bump BOND_TERMS.version,且只对新申报生效。
+ */
+export const BOND_TERMS = {
+    version: 'bond-terms.v1.2026-07-05',
+    zh: `【商家履约保证金条款 v1】
+1. 性质:本保证金是你(商家)向 WebAZ 平台缴纳的【履约担保物】(security deposit),用于担保你在直付(direct_p2p)交易中的履约义务。它不是投资、不是存款、不是买家资金,也不产生利息。
+2. 金额与币种:按平台公示档位(当前 T0 = 500 USDC 等值;固定 token 数,档位参考 ≈ S$500,非实时汇率换算)。可按平台公示的收款账户以 USDC 或对应法币缴纳;跨币种等值由平台运营在核实到账时按公示口径认定。
+3. 生效:缴纳后须经平台运营核实真实到账并确认锁定方才生效;申报本身不授予任何资格。
+4. 退还:你可申请退出并退还保证金。前提是【无任何未了结的直付责任】(在途订单、售后/退货流程、争议、待复核罚没、平台服务费欠费等),并经过平台公示的冷静期;冷静期内你的直付资格暂停,期间可随时撤销申请。退还在协议外原路/约定方式完成并留痕。
+5. 罚没(约定履约损害赔偿):仅当直付交易争议经平台仲裁【裁定你承担责任】后,平台方可发起罚没提案;提案设有公示冷静期(即你的申诉窗口),期满经人工复核后执行。你同意:被执行的罚没金额作为【约定的履约损害赔偿与生态修复金】全额转入平台处罚金专户 —— 该专户只进不出、不用于平台收益、不向个案裁决者发放,用途受治理公示约束。
+6. 链上风险:以 USDC 缴纳时,链、地址、金额由你自行核对;错链/错地址造成的损失由你承担。
+7. 条款版本:本条款版本化。你每次缴纳申报时同意的版本会被记录;条款更新只影响之后的新缴纳。
+8. 你确认:已阅读并理解上述条款,自愿缴纳。`,
+    en: `[Merchant Performance Bond Terms v1]
+1. Nature: this bond is a SECURITY DEPOSIT you (the merchant) place with the WebAZ platform to secure your fulfilment obligations in Direct Pay (direct_p2p) trades. It is not an investment, not a deposit account, not buyer funds, and bears no interest.
+2. Amount & currency: per the published tier (currently T0 = 500 USDC equivalent; a fixed token amount — the "≈ S$500" label is a tier reference, not a live FX conversion). Payable in USDC or the corresponding fiat via the platform's published receiving accounts; cross-currency equivalence is determined by platform operations at verification time per the published basis.
+3. Effectiveness: the bond takes effect only after platform operations verify the actual arrival of funds and confirm the lock; a declaration by itself grants nothing.
+4. Refund: you may request exit and refund, provided you have NO outstanding Direct Pay liabilities (open orders, after-sales/return flows, disputes, pending slash reviews, unpaid platform service fees, etc.) and after the published cooling window; your Direct Pay eligibility is suspended during the window and you may cancel the request at any time. The refund is completed off-protocol via the original/agreed channel and recorded.
+5. Slash (agreed liquidated damages): only after a Direct Pay dispute is RULED against you by platform arbitration may the platform open a slash proposal; the proposal carries a published cooling window (your appeal window) and is executed after human review. You agree that a slashed amount, as AGREED LIQUIDATED DAMAGES and ecosystem-remediation funds, is transferred in full to the platform's penalty reserve — inflow-only, never platform profit, never paid to per-case adjudicators, with usage bound by published governance.
+6. On-chain risk: when paying in USDC you are responsible for verifying the chain, address and amount; losses from wrong-chain/wrong-address transfers are yours.
+7. Versioning: these terms are versioned. The version you agree to at each declaration is recorded; updates affect only subsequent deposits.
+8. You confirm you have read and understood these terms and deposit voluntarily.`,
+};

package/dist/currency.js

@@ -0,0 +1,16 @@
+/**
+ * 协议展示币种(单一真相源)。
+ *
+ * 协议内部模拟单位对外一律显示为 **WAZ**(pre-launch 测试币;1 WAZ ≈ 1 USDC 是模拟基准,非真实汇率,无真实结算)。
+ * 历史遗留:products.currency 曾 DEFAULT 'DCP'(旧内部代号),存量行仍可能是 'DCP'。agent-facing 输出【绝不】暴露 'DCP' ——
+ *   读时经 displayCurrency() 归一化为 WAZ。底层 schema DEFAULT 的翻转 + 存量 backfill 是【独立 gated PR】(需 ALTER/回填决策),
+ *   本模块只保证【展示层】一致,不动数据。
+ */
+export const PROTOCOL_CURRENCY = 'WAZ';
+/** 归一化展示币种:空 / 'DCP'(遗留内部代号)→ 'WAZ';其余原样(大写)。用于所有 agent-facing 币种字段。 */
+export function displayCurrency(code) {
+    const c = typeof code === 'string' ? code.trim().toUpperCase() : '';
+    if (!c || c === 'DCP')
+        return PROTOCOL_CURRENCY;
+    return c;
+}

package/dist/deposit-rails.js

@@ -0,0 +1,52 @@
+/**
+ * 非生产确认:由真人 admin/operator 在【受控/测试环境】确认(不接真实链 / PSP)。
+ * ⚠️ TEST / ADMIN-ONLY —— **绝不可用于 production go-live**。它无条件返回 confirmed=true,不代表真实 base bond 到位。
+ *   生产收款侧必须:(a) 用 `assertProductionDepositRail()` 显式拒绝本轨;且 (b) 仅在 deposit 行
+ *   `production_receipt_confirmed_at` 非 NULL 时才视为担保物到位(manual 轨不写该列)。
+ */
+export const MANUAL_DEPOSIT_RAIL = {
+    id: 'manual',
+    isProduction: false,
+    implemented: true,
+    legalCleared: false,
+    confirmReceipt: ({ externalRef }) => ({ confirmed: true, externalRef: externalRef ?? 'manual' }),
+};
+/**
+ * operator-attested 生产轨:履约保证金走【公司企业账户(法币)/ 专项钱包地址(USDC 等)】线下/链上交存,
+ *   由 ROOT + 真人 Passkey 的运营在【核实到账后】凭 ref 记录确认。**本代码不收款、不持私钥、不签名、不划转**——
+ *   真实资金保管/退还是公司运营/托管方责任,代码只做"已核实"的记录 + 资格判定。
+ * 这是一条【已实现】的生产轨(implemented=true),但是否放行仍由 #112 rail-clearance registry(Lock B,治理默认关)决定:
+ *   在 ROOT 翻开放行开关之前,confirmProductionReceipt 仍因 Lock B 抛 → 全程 fail-closed。
+ */
+export const OPERATOR_ATTESTED_DEPOSIT_RAIL = {
+    id: 'operator_attested',
+    isProduction: true,
+    implemented: true,
+    legalCleared: false, // 信息位;放行由 registry/Lock B 治理开关决定,不在此置 true
+    confirmReceipt: ({ externalRef }) => ({ confirmed: true, externalRef: externalRef ?? 'operator_attested' }),
+};
+/**
+ * 生产闸(Lock A):生产 go-live 路径在依赖 base bond 到位前必须调用。要求 **isProduction 且 implemented**
+ *   (= 这是一条建好的生产轨)。legal/治理放行是【独立的 Lock B】(assertBondRailCleared / rail-clearance registry)。
+ * 现状:manual=非生产;usdc_onchain/fiat_psp=GATED 未实现 → 均抛;operator_attested 过 Lock A,但仍被 Lock B(默认关)挡。
+ */
+export function assertProductionDepositRail(rail) {
+    if (!rail.isProduction || !rail.implemented) {
+        throw new Error(`deposit-rail '${rail.id}' is NOT an implemented production rail (isProduction=${rail.isProduction}, implemented=${rail.implemented}) — cannot be used for production base-bond receipt; legal/governance clearance is enforced separately by the rail-clearance registry (Lock B)`);
+    }
+}
+/** 生产收款轨【GATED】—— 真钱/链上/PSP 自动集成未接,调用即抛。implemented=false → 也过不了 Lock A。 */
+function gated(id) {
+    return {
+        id, isProduction: true, implemented: false, legalCleared: false,
+        confirmReceipt: () => { throw new Error(`deposit-rail '${id}' is GATED: real-money/on-chain/PSP receipt not built (legal review: security-deposit characterisation + USDC DTSP + real-money boundary required)`); },
+    };
+}
+/** 取存款轨实现。manual=非生产;operator_attested=运营核实(已实现,放行仍由 Lock B 治理开关);usdc/fiat=GATED。显式 switch。 */
+export function getDepositRail(railId) {
+    if (railId === 'manual')
+        return MANUAL_DEPOSIT_RAIL;
+    if (railId === 'operator_attested')
+        return OPERATOR_ATTESTED_DEPOSIT_RAIL;
+    return gated(railId);
+}

package/dist/direct-pay-aml-monitor.js

@@ -0,0 +1,67 @@
+/**
+ * 治理可调 param 描述(供未来 launch-policy PR seed 进 DEFAULT_PARAMS;本 PR【不】改 server.ts —— 它已到 LOC 上限,
+ *   且默认值全 inert,monitor 经 getProtocolParam fallback 即用)。默认值是本模块各阈值的【单一真相源】(num() 回落到此)。
+ */
+export const DIRECT_PAY_AML_PARAMS = [
+    { key: 'direct_pay.aml.window_hours', value: '24', type: 'number', description: 'Direct Pay AML 监控回看窗口(小时)。默认 24。', category: 'system', min: 1 },
+    { key: 'direct_pay.aml.velocity_max_orders', value: '0', type: 'number', description: 'Direct Pay AML velocity 规则:窗口内卖家 direct_p2p 单数达此值即 flag(medium/open)。0=关闭(默认 inert)。', category: 'system', min: 0 },
+    { key: 'direct_pay.aml.small_order_amount', value: '0', type: 'number', description: 'Direct Pay AML concentration 规则:"小额单"判定阈值(与 orders.total_amount 同标度)。0=关闭。', category: 'system', min: 0 },
+    { key: 'direct_pay.aml.concentration_max_small_orders', value: '0', type: 'number', description: 'Direct Pay AML concentration 规则:窗口内小额单数达此值即 flag;需与 small_order_amount 同时 >0 方激活。0=关闭。', category: 'system', min: 0 },
+];
+/** 读非负数 param,脏值/缺失回落默认(默认 inert)。 */
+function num(gp, key, fb) {
+    const v = Number(gp(key, fb));
+    return Number.isFinite(v) && v >= 0 ? v : fb;
+}
+/** ISO → SQLite datetime('now') 同格式 'YYYY-MM-DD HH:MM:SS'(UTC,秒级),以便与 orders.created_at 做可比的字符串比较。 */
+function toSqliteTs(iso) {
+    return new Date(iso).toISOString().slice(0, 19).replace('T', ' ');
+}
+/**
+ * direct_p2p 建单成功后运行。按治理阈值检测窗口内卖家行为,命中即 append aml_flags。返回写入的 flag id 列表(可空)。
+ * 纯写 aml_flags(append-only);无其它副作用。绝不阻断/回滚当前订单。
+ */
+export function runDirectPayAmlMonitor(db, args) {
+    const { sellerId, orderId, nowIso, getProtocolParam: gp } = args;
+    const windowHours = num(gp, 'direct_pay.aml.window_hours', 24) || 24;
+    const maxOrders = num(gp, 'direct_pay.aml.velocity_max_orders', 0);
+    const smallAmt = num(gp, 'direct_pay.aml.small_order_amount', 0);
+    const maxSmall = num(gp, 'direct_pay.aml.concentration_max_small_orders', 0);
+    const since = toSqliteTs(new Date(new Date(nowIso).getTime() - windowHours * 3600_000).toISOString());
+    const flagsWritten = [];
+    const write = (rule, detail) => {
+        const id = `amlf_${rule}_${orderId}`;
+        const r = db.prepare(`INSERT OR IGNORE INTO aml_flags (id, subject_user_id, related_order_id, rule, severity, detail, status, disposition)
+       VALUES (?,?,?,?, 'medium', ?, 'open', 'review_queue')`).run(id, sellerId, orderId, rule, JSON.stringify(detail));
+        if (r.changes === 1)
+            flagsWritten.push(id);
+    };
+    // Rule 1 — velocity / cumulative:窗口内卖家 direct_p2p 单数 ≥ 阈值(阈值 >0 方激活)。
+    if (maxOrders > 0) {
+        const row = db.prepare("SELECT COUNT(*) n FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND created_at >= ?").get(sellerId, since);
+        if (row.n >= maxOrders)
+            write('velocity', { window_hours: windowHours, order_count: row.n, threshold: maxOrders });
+    }
+    // Rule 2 — concentration:窗口内小额(total_amount ≤ smallAmt)direct_p2p 单数 ≥ 阈值(两阈值都 >0 方激活)。
+    if (smallAmt > 0 && maxSmall > 0) {
+        const row = db.prepare("SELECT COUNT(*) n FROM orders WHERE seller_id = ? AND payment_rail = 'direct_p2p' AND total_amount <= ? AND created_at >= ?").get(sellerId, smallAmt, since);
+        if (row.n >= maxSmall)
+            write('concentration', { window_hours: windowHours, small_order_count: row.n, small_order_amount: smallAmt, threshold: maxSmall });
+    }
+    return { flagsWritten };
+}
+/**
+ * fail-soft 包装:监控写入异常【不得】破坏已提交的建单。建单成功后调用此函数(而非裸 runDirectPayAmlMonitor),
+ *   任何异常被吞并返回 { ok:false, error };绝不向上抛、绝不影响订单响应。
+ */
+export function safeRunDirectPayAmlMonitor(db, args) {
+    try {
+        const { flagsWritten } = runDirectPayAmlMonitor(db, args);
+        return { ok: true, flagsWritten };
+    }
+    catch (e) {
+        // 仅记录;绝不抛(订单已提交,监控失败不能回流成建单失败)。
+        console.error('[direct-pay-aml-monitor] non-fatal:', e.message);
+        return { ok: false, error: e.message };
+    }
+}

package/dist/direct-pay-aml-review.js

@@ -0,0 +1,40 @@
+import { randomUUID } from 'crypto';
+const VALID_DECISIONS = new Set(['clear', 'escalate', 'suspend']);
+/**
+ * 复核单条 aml_flag(唯一受控 writer)。成功返回 { ok:true, ...新状态 };参数/flag 非法返回 { ok:false, error }。
+ * 绝不抛(参数与存在性都显式校验)。
+ */
+export function reviewAmlFlag(db, args) {
+    const { flagId, reviewerId, decision } = args; // notes: 入参契约的一部分,但刻意不持久化(见文件头 PII/schema 说明)
+    if (!flagId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!VALID_DECISIONS.has(decision))
+        return { ok: false, error: 'INVALID_DECISION' };
+    const flag = db.prepare('SELECT id, subject_user_id, status FROM aml_flags WHERE id = ?')
+        .get(flagId);
+    if (!flag)
+        return { ok: false, error: 'FLAG_NOT_FOUND' };
+    // decision → (新 status, 新 disposition)。suspend 保留当前 status,只强制 disposition(breaker suspend 优先 → 继续阻断)。
+    let newStatus, newDisposition;
+    if (decision === 'clear') {
+        newStatus = 'cleared';
+        newDisposition = 'downgrade';
+    }
+    else if (decision === 'escalate') {
+        newStatus = 'escalated';
+        newDisposition = 'review_queue';
+    }
+    else {
+        newStatus = flag.status;
+        newDisposition = 'suspend';
+    }
+    db.transaction(() => {
+        // 只改复核相关列(status / disposition / reviewed_by / reviewed_at);notes 不落库(见文件头)。
+        db.prepare(`UPDATE aml_flags SET status = ?, disposition = ?, reviewed_by = ?, reviewed_at = datetime('now') WHERE id = ?`)
+            .run(newStatus, newDisposition, reviewerId, flagId);
+        // 审计(append-only;无 PII:仅内部 id + 决策 + 结果)。与 UPDATE 同事务 → 改 flag 必留痕。
+        db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+            .run('amlrev_' + randomUUID(), reviewerId, 'direct_pay.aml_review', 'aml_flag', flagId, JSON.stringify({ subject_user_id: flag.subject_user_id, decision, status: newStatus, disposition: newDisposition }));
+    })();
+    return { ok: true, flagId, subjectUserId: flag.subject_user_id, decision: decision, status: newStatus, disposition: newDisposition };
+}

package/dist/direct-pay-base-bond-entry.js

@@ -0,0 +1,5 @@
+import { sellerHasProductionBaseBondLocked } from './direct-receive-deposits.js';
+import { getActiveDeferral } from './direct-receive-deferral.js';
+export function sellerBaseBondEntrySatisfied(db, sellerId, nowIso) {
+    return sellerHasProductionBaseBondLocked(db, sellerId) || getActiveDeferral(db, sellerId, nowIso) != null;
+}

package/dist/direct-pay-bond-rail-clearance.js

@@ -0,0 +1,99 @@
+/**
+ * Direct Pay (Rail 1) — merchant production base-bond RAIL-CLEARANCE registry (Phase 4 scaffold)。
+ *
+ * 这是 production base-bond rail 走向上线前的【合规放行建模层】,默认【全 fail-closed】。它【不】启用真实生产收款、
+ *   【不】接 USDC/on-chain/PSP/bank、【不】实现 confirmReceipt 真实验证、【不】移动任何资金。
+ *
+ * 双锁模型(两把【独立】的锁,缺一即拒,confirmProductionReceipt 同时要求):
+ *   Lock A — 已实现锁:DepositRail 必须 isProduction && implemented(是不是一条建好的生产轨)。
+ *            manual=非生产;usdc/fiat=GATED(implemented=false);operator_attested=已实现 → 过 Lock A。由 assertProductionDepositRail 守。
+ *   Lock B — registry 放行锁(本模块):某 rail 的 legal_cleared + production_ready + 非占位 policy_version +
+ *            jurisdiction ∈ allowlist。当前【全部默认 fail-closed】→ 全拒。由 assertBondRailCleared 守。
+ *
+ * 现状(2026-07-05 更新):**operator_attested 轨已放行(SG)** —— Holden 决策 B(经营者知情自担风险,
+ *   非律师意见):保证金是商家履约担保物、不涉买家资金/货款;法币收取=常规合同担保物;USDC 收取的 PS Act
+ *   DPT 定性风险已知并接受(security-deposit 豁免待律师确认,确认前敞口=pre-launch 无真实商家)。前置已建:
+ *   条款文本+缴纳前强制同意(src/bond-terms.ts,liquidated-damages 表述;policy_version=条款版本,审计对齐)。
+ *   usdc_onchain / fiat_psp【自动收款轨】仍全 fail-closed(未实现+未清门,与本次放行无关)。
+ */
+import { getDepositRail } from './deposit-rails.js';
+/** policy_version 占位值(= 未设)。等于此值即视为未放行。 */
+export const BOND_POLICY_VERSION_PLACEHOLDER = 'pre-legal-unset';
+/**
+ * 生产 base-bond rail 放行 registry。【显式 switch / 常量,无注册框架】(anti-YAGNI,镜像 deposit-rails.ts)。
+ * 只登记【生产收款轨】(usdc_onchain / fiat_psp);manual = 非生产确认轨,不在此(查询返回 null → fail-closed)。
+ * 全部默认 fail-closed —— 真值由后续【法务清门 + 外审】PR 配置,不在本 scaffold。
+ */
+const BOND_RAIL_CLEARANCE = {
+    // ✅ 2026-07-05 放行(Holden 决策 B,经营者知情自担;详见文件头)。policy_version = 条款版本(bond-terms.ts,
+    //   缴纳前强制同意)。运营就绪:B1 申报/核实队列 + confirm-production(ROOT+Passkey)+ B2 退还 + B3 罚没全链已建。
+    operator_attested: { railId: 'operator_attested', assetCategory: 'usdc_fiat', legalCleared: true, jurisdictionAllowlist: ['SG'], policyVersion: 'bond-terms.v1.2026-07-05', productionReady: true },
+    // 自动收款轨:未实现(Lock A 也拒),维持全 fail-closed —— 与 operator_attested 放行无关。
+    usdc_onchain: { railId: 'usdc_onchain', assetCategory: 'usdc', legalCleared: false, jurisdictionAllowlist: [], policyVersion: BOND_POLICY_VERSION_PLACEHOLDER, productionReady: false },
+    fiat_psp: { railId: 'fiat_psp', assetCategory: 'fiat', legalCleared: false, jurisdictionAllowlist: [], policyVersion: BOND_POLICY_VERSION_PLACEHOLDER, productionReady: false },
+};
+/** 取某 rail 的放行记录;未登记(如 manual / 未知)→ null(fail-closed)。 */
+export function getBondRailClearance(railId) {
+    return BOND_RAIL_CLEARANCE[railId] ?? null;
+}
+/**
+ * 该 rail 在该 jurisdiction 下是否【可用于生产 base-bond】= Lock A(真实实现)且 Lock B(registry 放行)全过。
+ * jurisdiction 语义=【平台收款主体法域】(非卖家法域)。2026-07-05 起 operator_attested/SG 为 true(#240)。纯读,无副作用。
+ */
+export function isBondRailClearedForProduction(railId, jurisdiction) {
+    const c = getBondRailClearance(railId);
+    if (!c)
+        return false;
+    // Lock A:已实现的生产收款轨(deposit-rails)。与 assertProductionDepositRail 一致用 implemented(非 legalCleared)——
+    //   legal/治理放行全归 Lock B(本函数下半段 registry)。manual=非生产;usdc/fiat=GATED(implemented=false)。
+    let rail;
+    try {
+        rail = getDepositRail(railId);
+    }
+    catch {
+        return false;
+    }
+    if (!rail.isProduction || !rail.implemented)
+        return false;
+    // Lock B:registry 放行(全字段)。
+    return c.legalCleared && c.productionReady
+        && c.policyVersion !== BOND_POLICY_VERSION_PLACEHOLDER && c.policyVersion.length > 0
+        && typeof jurisdiction === 'string' && jurisdiction.length > 0
+        && c.jurisdictionAllowlist.includes(jurisdiction);
+}
+/**
+ * 生产 base-bond 放行【硬闸】(Lock B 入口):未完全放行即抛。confirmProductionReceipt 在 assertProductionDepositRail
+ *   (Lock A)之后【额外】调用本闸 —— 两把独立锁都过才可能写 production receipt。当前恒抛。
+ */
+export function assertBondRailCleared(railId, jurisdiction) {
+    if (!isBondRailClearedForProduction(railId, jurisdiction)) {
+        throw new Error(`bond rail '${railId}' is NOT legal-cleared for production (jurisdiction='${jurisdiction}'; blockers=${bondRailClearanceBlockers(railId).join(',') || 'none'}) — production base-bond receipt cannot be confirmed`);
+    }
+}
+/**
+ * 只读 readiness/blockers —— 列出某 rail 距离生产放行还差什么(供后续 Phase 7 readiness 面 / 运维诊断,不带 UI/endpoint)。
+ * opts.hasProductionReceipt:某具体 deposit 是否已有 production_receipt_confirmed_at(per-deposit,调用方提供事实)。
+ * 当前任何 rail 都至少含 RAIL_IMPLEMENTATION_GATED / NO_LEGAL_CLEARED_RAIL / EMPTY_JURISDICTION_ALLOWLIST / POLICY_VERSION_UNSET。
+ */
+export function bondRailClearanceBlockers(railId, opts) {
+    const out = [];
+    let rail = null;
+    try {
+        rail = getDepositRail(railId);
+    }
+    catch {
+        rail = null;
+    }
+    if (!rail || !rail.isProduction || !rail.implemented)
+        out.push('RAIL_IMPLEMENTATION_GATED');
+    const c = getBondRailClearance(railId);
+    if (!c || !c.legalCleared || !c.productionReady)
+        out.push('NO_LEGAL_CLEARED_RAIL');
+    if (!c || c.jurisdictionAllowlist.length === 0)
+        out.push('EMPTY_JURISDICTION_ALLOWLIST');
+    if (!c || c.policyVersion === BOND_POLICY_VERSION_PLACEHOLDER || c.policyVersion.length === 0)
+        out.push('POLICY_VERSION_UNSET');
+    if (opts?.hasProductionReceipt !== true)
+        out.push('NO_PRODUCTION_RECEIPT');
+    return out;
+}