@seasonkoh/webaz 0.1.28 → 0.1.29

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/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,94 @@
+/**
+ * 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 守。
+ *
+ * 现状:本模块所有 rail 的 legal_cleared=false / allowlist=[] / policy_version=占位 / production_ready=false,
+ *   且 Lock A 也全拒 → isBondRailClearedForProduction 恒 false → confirmProductionReceipt 恒抛 →
+ *   sellerHasProductionBaseBondLocked 恒 false → Direct Pay 仍 non-launchable / fail-closed。
+ *   置真值(legal_cleared / 真实 allowlist / 真实 policy_version / production_ready)= 法务清门 + 外审 gated 决定,【不在本 PR】。
+ */
+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 = {
+    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 放行)全过。
+ * 当前恒 false。纯读,无副作用。
+ */
+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;
+}

package/dist/direct-pay-compliance-ingress.js

@@ -0,0 +1,145 @@
+import { randomUUID, createHash } from 'crypto';
+// ── allowlists(未知值 fail-closed)──
+const KYB_STATUSES = new Set(['pending', 'approved', 'rejected', 'revoked']);
+const SANCTIONS_STATUSES = new Set(['clear', 'flagged', 'blocked']);
+const AML_RULES = new Set(['structuring', 'concentration', 'cumulative', 'crypto', 'velocity']);
+const AML_SEVERITIES = new Set(['low', 'medium', 'high']);
+const AML_STATUSES = new Set(['open', 'reviewing', 'cleared', 'escalated', 'str_filed']);
+// expires_at 形态:reader 用 `expires_at > datetime('now')` 做【字符串比较】,datetime('now') = 'YYYY-MM-DD HH:MM:SS'。
+//   任意字符串(如 'not-a-date')会被字典序当成"未来"→ 错误地通过 fail-closed reader。故 ingress 必须校验+规范化:
+//   只接受 SQLite datetime 'YYYY-MM-DD HH:MM:SS' 或完整 ISO-8601,且能真实解析;ISO 一律规范化为可比的 SQLite 格式。
+// SQLite UTC civil 形态 'YYYY-MM-DD HH:MM:SS';ISO 形态【强制带 timezone】(Z 或 ±hh:mm)——无 tz 会按服务器本地时区归一,拒。
+const SQLITE_DT_RE = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})$/;
+const ISO_DT_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+/**
+ * 逐字段校验【真实存在】的 civil datetime —— 用 Date.UTC 重建后逐字段回比,杜绝 JS 自动滚动
+ *   (如 2099-02-31 → 03-03、25:00 → 次日)。把字段当 UTC 校验真实性即可(与 SQLite datetime('now') UTC 语义一致)。
+ */
+function isRealCivil(y, mo, d, h, mi, s) {
+    const t = Date.UTC(y, mo - 1, d, h, mi, s);
+    if (!Number.isFinite(t))
+        return false;
+    const dt = new Date(t);
+    return dt.getUTCFullYear() === y && dt.getUTCMonth() === mo - 1 && dt.getUTCDate() === d
+        && dt.getUTCHours() === h && dt.getUTCMinutes() === mi && dt.getUTCSeconds() === s;
+}
+/**
+ * 校验+规范化 expiresAt:空→null(无期限,允许);合法→可比的 'YYYY-MM-DD HH:MM:SS'(UTC);非法→ false。
+ * 不依赖 Date.parse 的宽松解析:先正则定形、再逐字段 isRealCivil 校验(拒不存在的日期),ISO 必须显式带 tz。
+ */
+export function normalizeExpiry(expiresAt) {
+    if (expiresAt === undefined || expiresAt === null || expiresAt === '')
+        return { ok: true, value: null };
+    const sm = SQLITE_DT_RE.exec(expiresAt);
+    if (sm) {
+        if (!isRealCivil(+sm[1], +sm[2], +sm[3], +sm[4], +sm[5], +sm[6]))
+            return { ok: false };
+        return { ok: true, value: expiresAt }; // 已是可比的 UTC civil 形态
+    }
+    const im = ISO_DT_RE.exec(expiresAt);
+    if (im) {
+        // 先逐字段校验【字面 civil 日期】真实存在(2099-02-31 此处即被拒,与 tz 无关)。
+        if (!isRealCivil(+im[1], +im[2], +im[3], +im[4], +im[5], +im[6]))
+            return { ok: false };
+        const ms = Date.parse(expiresAt); // 字面已合法 + 强制带 tz → 此处只做 tz 偏移换算得真实 UTC instant
+        if (!Number.isFinite(ms))
+            return { ok: false };
+        return { ok: true, value: new Date(ms).toISOString().slice(0, 19).replace('T', ' ') };
+    }
+    return { ok: false };
+}
+/** providerRef → 审计用短引用(sha256 前 16 hex);无则 undefined。原值不进审计明文。 */
+function providerRefHash(providerRef) {
+    if (!providerRef)
+        return undefined;
+    return createHash('sha256').update(providerRef).digest('hex').slice(0, 16);
+}
+/**
+ * AML detail allowlist key 集 —— 与 #108 monitor 实际写入的聚合字段一致(velocity/concentration)。
+ * key 也走 allowlist(不止 value):杜绝把 PII 藏进 key(如 {"alice@example.com":1} / {"wallet_0x..":1})。
+ */
+export const AML_DETAIL_KEYS = new Set(['window_hours', 'order_count', 'threshold', 'small_order_count', 'small_order_amount']);
+/**
+ * AML detail = 仅【allowlist key + 聚合数字 value】(与 #108 monitor 纪律一致,防 PII 落库:
+ *   邮箱/地址/钱包/叙述性笔记无论藏在 value 还是 key 一律拒)。undefined 视为"无 detail"(合法)。
+ */
+export function isNumericDetail(detail) {
+    if (detail === undefined || detail === null)
+        return true;
+    if (typeof detail !== 'object' || Array.isArray(detail))
+        return false;
+    return Object.entries(detail).every(([k, v]) => AML_DETAIL_KEYS.has(k) && typeof v === 'number' && Number.isFinite(v));
+}
+/**
+ * AML detail 的 canonical hash(key 排序后 JSON → sha256 前 16 hex),供 Passkey purpose_data 绑定【写入内容】用
+ *   (route 与签名方用同一函数,保证"签的 detail = 写的 detail")。无 detail → 固定 'none'。
+ */
+export function amlDetailHash(detail) {
+    if (detail === undefined || detail === null)
+        return 'none';
+    const canonical = JSON.stringify(Object.keys(detail).sort().reduce((o, k) => { o[k] = detail[k]; return o; }, {}));
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+/** 审计写入(append-only;PII-free)。与台账 INSERT 同事务调用。 */
+function writeAudit(db, adminId, action, targetType, targetId, detail) {
+    db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+        .run('cing_' + randomUUID(), adminId, action, targetType, targetId, JSON.stringify(detail));
+}
+/** KYB 复核结论 ingress(append-only)。status ∈ {pending,approved,rejected,revoked}。 */
+export function recordKybReview(db, args) {
+    const { userId, reviewerId, status, providerRef, expiresAt } = args;
+    if (!userId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!KYB_STATUSES.has(status))
+        return { ok: false, error: 'INVALID_STATUS' };
+    const exp = normalizeExpiry(expiresAt);
+    if (!exp.ok)
+        return { ok: false, error: 'INVALID_EXPIRES_AT' };
+    const id = 'kyb_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO direct_receive_kyb_reviews (id, user_id, status, reviewed_by, reviewed_at, expires_at, reason)
+      VALUES (?,?,?,?,datetime('now'),?,?)`).run(id, userId, status, reviewerId, exp.value, providerRef ?? null);
+        writeAudit(db, reviewerId, 'direct_pay.kyb_ingress', 'user', userId, { kyb_status: status, provider_ref_hash: providerRefHash(providerRef), has_expiry: !!expiresAt, review_id: id });
+    })();
+    return { ok: true, id };
+}
+/** 制裁筛查结论 ingress(append-only)。status ∈ {clear,flagged,blocked}。 */
+export function recordSanctionsScreening(db, args) {
+    const { userId, reviewerId, status, providerRef, expiresAt } = args;
+    if (!userId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!SANCTIONS_STATUSES.has(status))
+        return { ok: false, error: 'INVALID_STATUS' };
+    const exp = normalizeExpiry(expiresAt);
+    if (!exp.ok)
+        return { ok: false, error: 'INVALID_EXPIRES_AT' };
+    const id = 'sc_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO sanctions_screening (id, user_id, status, source, reason, screened_at, expires_at)
+      VALUES (?,?,?,?,?,datetime('now'),?)`).run(id, userId, status, 'manual_ingress', providerRef ?? null, exp.value);
+        writeAudit(db, reviewerId, 'direct_pay.sanctions_ingress', 'user', userId, { sanctions_status: status, provider_ref_hash: providerRefHash(providerRef), has_expiry: !!expiresAt, screening_id: id });
+    })();
+    return { ok: true, id };
+}
+/** AML flag ingress(append-only,新建 flag)。rule/severity/status 全 allowlist。 */
+export function recordAmlFlagIngress(db, args) {
+    const { userId, reviewerId, rule, severity, status, relatedOrderId, detail } = args;
+    if (!userId || !reviewerId)
+        return { ok: false, error: 'MISSING_ARGS' };
+    if (!AML_RULES.has(rule))
+        return { ok: false, error: 'INVALID_RULE' };
+    if (!AML_SEVERITIES.has(severity))
+        return { ok: false, error: 'INVALID_SEVERITY' };
+    if (!AML_STATUSES.has(status))
+        return { ok: false, error: 'INVALID_STATUS' };
+    // P2: detail 仅允许聚合数字(防 PII 落库)。非纯数字 → fail-closed,不写。
+    if (!isNumericDetail(detail))
+        return { ok: false, error: 'INVALID_DETAIL' };
+    const id = 'amlf_' + randomUUID();
+    db.transaction(() => {
+        db.prepare(`INSERT INTO aml_flags (id, subject_user_id, related_order_id, rule, severity, detail, status)
+      VALUES (?,?,?,?,?,?,?)`).run(id, userId, relatedOrderId ?? null, rule, severity, detail ? JSON.stringify(detail) : null, status);
+        writeAudit(db, reviewerId, 'direct_pay.aml_ingress', 'aml_flag', id, { subject_user_id: userId, rule, severity, aml_status: status, related_order_id: relatedOrderId ?? null });
+    })();
+    return { ok: true, id };
+}

package/dist/direct-pay-controls.js

@@ -0,0 +1,136 @@
+// PR-6D: 把 #108 的 AML 监控 param 描述(默认 inert)经控制面统一再导出,使 server.ts DEFAULT_PARAMS
+//   可在【既有 import 行】上一并取用(server.ts 已到 LOC 上限,避免新增行)。SSOT 仍在 direct-pay-aml-monitor.ts。
+export { DIRECT_PAY_AML_PARAMS } from './direct-pay-aml-monitor.js';
+// ── buyer-facing de-identification(SSOT)─────────────────────────────────────────────────────────
+// 买家边界脱敏:卖家【私密类】拒因(暂停 / 保证金未交 / KYC·制裁 / AML / 缓交额度)一律收敛为单一
+//   DIRECT_PAY_SELLER_NOT_ELIGIBLE,绝不向买家暴露卖家具体合规/额度状态。全局/运营类(DISABLED / RAIL_BREAKER /
+//   REGION / CAP)非敏感,原样透出。create 与 availability 两个买家面端点【共用】本判定,避免 de-id 集合漂移。
+//   精确 code 仍保留在 helper 返回值 + 单测(controls / deferral-quota)层,供运营/调试与 gate 逻辑验证。
+//   缓交额度码须与 direct-pay-deferral-quota.ts 的 DEFERRAL_QUOTA_CODES 对齐(test-direct-pay-deferral-quota 漂移断言守护)。
+export const DIRECT_PAY_SELLER_NOT_ELIGIBLE = 'DIRECT_PAY_SELLER_NOT_ELIGIBLE';
+export const BUYER_FACING_SELLER_PRIVATE_CODES = new Set([
+    'DIRECT_PAY_SELLER_SUSPENDED', 'DIRECT_PAY_NOT_AVAILABLE', 'DIRECT_PAY_KYC_REQUIRED', 'DIRECT_PAY_AML_REVIEW_REQUIRED',
+    'DIRECT_PAY_DEFERRAL_QUOTA_EXCEEDED', 'DIRECT_PAY_DEFERRAL_AMOUNT_EXCEEDED',
+    'EXPOSURE_CAP_EXCEEDED', 'EXPOSURE_CAP_CONFIG', // §6.5 抵押背书敞口上限:卖家私密风险态,不向买家泄露
+    'FEE_PREPAY_INSUFFICIENT', // 平台服务费预充值余额不足(非首单):卖家私密风险态,不向买家泄露
+]);
+/** 买家面脱敏:私密拒因 → 通用 SELLER_NOT_ELIGIBLE;全局/运营类原样;undefined → 通用(fail-safe,绝不泄露)。 */
+export function coarsenBuyerFacingDirectPayCode(code) {
+    return !code || BUYER_FACING_SELLER_PRIVATE_CODES.has(code) ? DIRECT_PAY_SELLER_NOT_ELIGIBLE : code;
+}
+export const DEFAULT_DIRECT_PAY_CONTROLS = {
+    enabled: false, railBreakerTripped: false, region: '', regionAllowlist: [], perTxCapUnits: 0,
+};
+const isNonNegUnits = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+/**
+ * 入口控制判定(纯、fail-closed、total)。顺序(便宜/广 → 卖家专属 → 硬不变量):
+ *   全局开关 → 运营熔断 → 地区 → 单笔上限 → 卖家熔断 → production base-bond → KYC/制裁 → AML 断路器。
+ *   任一不过即返回该项拒绝码(短路;先全局/政策、后卖家专属,避免提前泄露卖家专属原因);全过返回 { ok:true }。绝不抛错。
+ *   production base-bond、KYC/制裁、AML 断路器都是【不可配置硬不变量】(无 cfg 开关、治理不可绕过),恒在最后强制。
+ */
+export function evaluateDirectPayLaunchControls(cfg, facts) {
+    const c = { ...DEFAULT_DIRECT_PAY_CONTROLS, ...(cfg ?? {}) };
+    const f = facts ?? {};
+    const deny = (error_code, reason) => ({ ok: false, status: 409, error_code, reason });
+    if (c.enabled !== true)
+        return deny('DIRECT_PAY_DISABLED', '直付当前未开放(全局开关关闭)');
+    if (c.railBreakerTripped === true)
+        return deny('DIRECT_PAY_RAIL_BREAKER', '直付已被运营紧急熔断,暂停受理');
+    const allow = Array.isArray(c.regionAllowlist) ? c.regionAllowlist : [];
+    if (!allow.length || !c.region || !allow.includes(c.region))
+        return deny('DIRECT_PAY_REGION_UNSUPPORTED', '直付在本地区暂未开放');
+    if (!isNonNegUnits(c.perTxCapUnits) || c.perTxCapUnits <= 0)
+        return deny('DIRECT_PAY_CAP_EXCEEDED', '直付单笔上限未配置');
+    if (!isNonNegUnits(f.amountUnits) || f.amountUnits <= 0 || f.amountUnits > c.perTxCapUnits)
+        return deny('DIRECT_PAY_CAP_EXCEEDED', '直付订单总额超出单笔上限(WebAZ 记录的订单金额上限;不约束场外实付)');
+    if (f.sellerBreakerTripped === true)
+        return deny('DIRECT_PAY_SELLER_SUSPENDED', '该卖家直付已被暂停');
+    // 硬不变量(launch blockers):production base-bond 与 KYC/制裁【始终强制】,无 cfg 开关、治理不可绕过。
+    if (f.baseBondSatisfied !== true)
+        return deny('DIRECT_PAY_NOT_AVAILABLE', '直付暂不可用:卖家未交履约保证金且无有效缓交');
+    if (f.kycSanctionsPassed !== true)
+        return deny('DIRECT_PAY_KYC_REQUIRED', '直付暂不可用:卖家未通过 KYC/制裁筛查');
+    if (f.amlClear !== true)
+        return deny('DIRECT_PAY_AML_REVIEW_REQUIRED', '直付暂不可用:卖家存在未清除的 AML 风险复核');
+    return { ok: true, status: 200 };
+}
+/** protocol_params 薄装配器(治理可调;缺行回落 fail-closed 默认)。不读资金/状态,只读控制参数。 */
+export function readDirectPayControlsConfig(getProtocolParam) {
+    const csv = String(getProtocolParam('direct_pay.region_allowlist', '') || '');
+    const cap = Number(getProtocolParam('direct_pay.per_tx_cap_units', 0));
+    return {
+        enabled: getProtocolParam('direct_pay.enabled', false) === true,
+        railBreakerTripped: getProtocolParam('direct_pay.rail_breaker_tripped', false) === true,
+        region: String(getProtocolParam('direct_pay.region', '') || ''),
+        regionAllowlist: csv.split(',').map(s => s.trim()).filter(Boolean),
+        perTxCapUnits: Number.isSafeInteger(cap) && cap >= 0 ? cap : 0,
+    };
+}
+/**
+ * protocol_params 默认 seed(供 server.ts DEFAULT_PARAMS 展开)。默认全 fail-closed —— Direct Pay non-launchable;
+ *   治理经 PATCH /api/admin/protocol-params/<key> 开通(无 seed 则 PATCH 404、boot 不建行 → 控制面打不开)。
+ *   只含【运营节流】可调项(开关/地区/上限)。production base-bond 与 KYC/制裁是【不可关闭的硬不变量】,
+ *   刻意【不】做成 param —— 治理无法关掉它们绕过 launch blockers(evaluate 始终强制)。
+ *   key/默认值必须与 readDirectPayControlsConfig / DEFAULT_DIRECT_PAY_CONTROLS 对齐。
+ */
+export const DIRECT_PAY_CONTROL_PARAMS = [
+    { key: 'direct_pay.enabled', value: 'false', type: 'boolean', description: 'Direct Pay 全局主开关(上线决定);默认 false=关(non-launchable)。', category: 'system' },
+    { key: 'direct_pay.rail_breaker_tripped', value: 'false', type: 'boolean', description: 'Direct Pay 运营紧急熔断(ops emergency stop,与 enabled 分离);true=暂停受理。默认 false。', category: 'system' },
+    { key: 'direct_pay.region', value: '', type: 'string', description: 'Direct Pay 本部署/运营所在地区码(与白名单比对);默认空=fail-closed。', category: 'system' },
+    { key: 'direct_pay.region_allowlist', value: '', type: 'string', description: 'Direct Pay 已开放地区白名单(逗号分隔);默认空=无地区开放。', category: 'system' },
+    // 单笔上限:对【WebAZ 记录的 direct_p2p 订单总额】在建单时的天花板(整数 policy base-units)。默认 0 = 无放行(fail-closed),
+    //   治理设正值方生效。【不是】对买卖双方场外真实付款金额的担保或控制——WebAZ 控不了场外金额,此处也不声称能控。
+    //   具体数值(如 SG v1 的 policy units)由独立的 launch-policy PR 配置,本 PR 只提供 cap 能力、默认仍 fail-closed。
+    { key: 'direct_pay.per_tx_cap_units', value: '0', type: 'number', description: 'Direct Pay 单笔上限:WebAZ 记录的订单总额天花板(整数 policy base-units);默认 0=无放行,治理设正值方可。仅约束协议侧建单金额,不控制/不担保场外真实付款。', category: 'system', min: 0 },
+    { key: 'direct_pay.exposure_factor_bps', value: '8000', type: 'number', description: '§6.5 抵押背书的开放敞口上限系数(bps):open_exposure + new_order ≤ active_collateral × bps/10000。仅对有真实链上抵押(collateral>0)的卖家生效;缓交卖家不受此门。默认 8000(=80%)。风险控制,非买家赔付。', category: 'system', min: 1, max: 10000 },
+    // 注:平台服务费门 = 首单宽限 + 预充值续用(数据驱动:available_prepay = Σ预充值 − Σ已计提费),【无 protocol_param 旋钮】
+    //   (额度即商家实际预付余额,宽限自动判定);故此处不再有 fee_ar_credit_ceiling_units 参数。
+];
+/**
+ * PR-6A AML/CFT runtime — KYB(商户尽调)事实(fail-closed)。来源 direct_receive_kyb_reviews(真人/合规复核结论;
+ *   无第三方 vendor、无真实 API 调用)。通过 ⟺ 存在 status='approved' 且未过期的复核 且【无】rejected/revoked 行。
+ *   missing / pending / rejected / revoked / expired 一律不通过。该表无生产写入方 → 真实卖家天然 fail-closed。
+ */
+export function sellerDirectPayKybPassed(db, sellerId) {
+    const approved = db.prepare("SELECT 1 FROM direct_receive_kyb_reviews WHERE user_id = ? AND status = 'approved' AND (expires_at IS NULL OR expires_at > datetime('now')) LIMIT 1").get(sellerId);
+    const blocked = db.prepare("SELECT 1 FROM direct_receive_kyb_reviews WHERE user_id = ? AND status IN ('rejected','revoked') LIMIT 1").get(sellerId);
+    return !!approved && !blocked;
+}
+/**
+ * PR-6A AML/CFT runtime — 制裁筛查事实(fail-closed)。来源 sanctions_screening:存在 status='clear' 且未过期的结论,
+ *   且【无】flagged/blocked 行。expired(expires_at 已过)视作未通过;NULL expires_at = 无期限。无第三方集成。
+ *   该表无生产写入方 → 真实卖家天然 fail-closed。
+ */
+export function sellerDirectPaySanctionsClear(db, sellerId) {
+    const clear = db.prepare("SELECT 1 FROM sanctions_screening WHERE user_id = ? AND status = 'clear' AND (expires_at IS NULL OR expires_at > datetime('now')) LIMIT 1").get(sellerId);
+    const bad = db.prepare("SELECT 1 FROM sanctions_screening WHERE user_id = ? AND status IN ('flagged','blocked') LIMIT 1").get(sellerId);
+    return !!clear && !bad;
+}
+/**
+ * 卖家熔断事实(per-seller breaker)。【唯一来源】= direct_receive_privileges.status = 'suspended'(复用既有暂停语义,
+ *   如 slashBond 罚没后置 suspended);【不】新增第二套 suspension 概念。无行 / 'none' / 'active' → false;'suspended' → true。
+ */
+export function sellerDirectPayBreakerTripped(db, sellerId) {
+    return !!db.prepare("SELECT 1 FROM direct_receive_privileges WHERE user_id = ? AND status = 'suspended' LIMIT 1").get(sellerId);
+}
+/**
+ * PR-6B AML 运行期断路器事实(fail-closed)。来源 aml_flags(本仓内部监控 flag;无第三方 vendor、无真实 API)。
+ *   key = subject_user_id。返回 true(清白/不阻断)⟺ 卖家【没有任何阻断性 flag】。
+ *
+ * 单条 flag 的【阻断】判定(任一命中即阻断;precedence 由 SQL OR 短路保证 suspend 优先于 cleared):
+ *   ① malformed enum —— severity/status/disposition 越界(本表 TEXT 无 CHECK,脏值可入)→ fail-closed 阻断;
+ *   ② disposition='suspend' —— 无论 severity/status【一律阻断】(含 status='cleared' 的矛盾数据:suspend 取胜,从严);
+ *   ③ status∈(open|reviewing|escalated|str_filed) 且 severity∈(medium|high) —— 未清除的中/高风险 → 阻断。
+ * 非阻断(放行):无 flag / status='cleared'(且非 suspend) / severity='low'(且非 suspend)。
+ *   纯读;不写;不碰资金/状态机。aml_flags 当前无生产写入方 → 真实卖家天然无阻断(待 AML 检测引擎接入再产生 flag)。
+ */
+export function sellerDirectPayAmlClear(db, sellerId) {
+    const blocking = db.prepare(`SELECT 1 FROM aml_flags WHERE subject_user_id = ? AND (
+         severity NOT IN ('low','medium','high')
+      OR status   NOT IN ('open','reviewing','cleared','escalated','str_filed')
+      OR (disposition IS NOT NULL AND disposition NOT IN ('review_queue','downgrade','suspend'))
+      OR disposition = 'suspend'
+      OR (status IN ('open','reviewing','escalated','str_filed') AND severity IN ('medium','high'))
+    ) LIMIT 1`).get(sellerId);
+    return !blocking;
+}