@seasonkoh/webaz 0.1.29 → 0.1.30

package/dist/runtime/webaz-schema-helpers.js

@@ -784,6 +784,17 @@ export function initArbitratorReviewSchema(db) {
     stake_amount    INTEGER DEFAULT 0
   )
 `);
+    // PR-B 生产仲裁员生命周期字段(ADD COLUMN 必在 CREATE 后 —— schema 铁律)。legacy 行 status NULL 视为 active。
+    for (const alter of [
+        `ALTER TABLE arbitrator_whitelist ADD COLUMN status TEXT DEFAULT 'active'`, // active | suspended | revoked
+        `ALTER TABLE arbitrator_whitelist ADD COLUMN suspended_at TEXT`,
+        `ALTER TABLE arbitrator_whitelist ADD COLUMN revoked_at TEXT`,
+    ]) {
+        try {
+            db.exec(alter);
+        }
+        catch { /* 列已存在 */ }
+    }
     try {
         db.exec('CREATE INDEX IF NOT EXISTS idx_arb_apps_status ON arbitrator_applications(status)');
     }
@@ -1220,7 +1231,7 @@ export function initReturnRequestsSchema(db) {
     reason               TEXT NOT NULL,          -- 'quality' | 'wrong_item' | 'damaged' | 'no_longer_needed' | 'other'
     reason_text          TEXT,
     refund_amount        DECIMAL(18,2),          -- 默认 = order.total_amount
-    status               TEXT NOT NULL DEFAULT 'pending', -- pending | accepted | rejected | refunded | escalated | cancelled
+    status               TEXT NOT NULL DEFAULT 'pending', -- pending | accepted | rejected | refunded | escalated | cancelled | (direct_p2p) await_refund | refund_marked
     seller_response      TEXT,
     escalated_dispute_id TEXT,
     created_at           TEXT DEFAULT (datetime('now')),
@@ -1239,6 +1250,15 @@ export function initReturnRequestsSchema(db) {
         db.exec('CREATE INDEX IF NOT EXISTS idx_returns_order ON return_requests(order_id)');
     }
     catch { }
+    // 直付(direct_p2p)送达后退货·场外退款握手(src/direct-pay-returns.ts)。ALTER 必须在 CREATE 之后(fresh DB silent-fail 铁律)。
+    try {
+        db.exec('ALTER TABLE return_requests ADD COLUMN refund_reference TEXT');
+    }
+    catch { /* 已存在 */ }
+    try {
+        db.exec('ALTER TABLE return_requests ADD COLUMN await_refund_since TEXT');
+    }
+    catch { /* 已存在 */ }
 }
 // ─── W2 售后协商时间线（flagged/flag_reasons ALTER 刻意留 server.ts 原位）──
 export function initReturnMessagesSchema(db) {
@@ -1784,13 +1804,47 @@ export function initAgentDelegationGrantsSchema(db) {
       created_at      TEXT NOT NULL DEFAULT (datetime('now')),
       expires_at      TEXT NOT NULL,                    -- short-lived (clamped, RFC-020 bearer-first)
       revoked_at      TEXT,
-      revoked_reason  TEXT
+      revoked_reason  TEXT,
+      permission_bundle TEXT                            -- named bundle key if issued/expanded via a bundle (e.g. 'catalog_agent'); NULL = ad-hoc scopes
     )
   `);
+    try {
+        db.exec(`ALTER TABLE agent_delegation_grants ADD COLUMN permission_bundle TEXT`);
+    }
+    catch { /* existing DB: column already added */ }
     db.exec(`CREATE INDEX IF NOT EXISTS idx_adg_human  ON agent_delegation_grants(human_id, status)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_adg_token  ON agent_delegation_grants(token_hash)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_adg_expiry ON agent_delegation_grants(status, expires_at)`);
 }
+/**
+ * RFC-020 — Agent Permission Requests (JIT + bundle authorization). An already-connected agent (holds a
+ * grant) that hits a missing scope, or wants a job bundle, lodges a REQUEST here; the human sees it in
+ * #agent-approvals and approves/rejects. Approval expands the agent's existing grant (safe scopes only,
+ * duration-capped). Bound to (human_id, grant_id). NO money/order/status columns; a request grants nothing
+ * until a human approves it.
+ */
+export function initAgentPermissionRequestsSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS agent_permission_requests (
+      id               TEXT PRIMARY KEY,                 -- apr_xxx
+      human_id         TEXT NOT NULL,                    -- resolved from the requesting agent's grant
+      grant_id         TEXT NOT NULL,                    -- the agent's existing grant that approval expands
+      agent_label      TEXT,
+      requested_scopes TEXT NOT NULL DEFAULT '[]',       -- JSON string[] — resolved (bundle expanded) safe scopes
+      permission_bundle TEXT,                            -- bundle key if requested as a bundle; NULL = ad-hoc
+      reason           TEXT,                             -- agent free-text (display only, unverified)
+      task_context     TEXT,                             -- agent free-text about the task (display only)
+      risk_level       TEXT NOT NULL DEFAULT 'low',      -- low | medium | high (derived, not agent-supplied)
+      duration         TEXT NOT NULL DEFAULT '7d',       -- once | 1h | 24h | 7d | 30d (capped by risk tier)
+      status           TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | rejected | expired | revoked
+      created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+      expires_at       TEXT NOT NULL,                    -- request TTL (auto-expire if unanswered)
+      approved_at      TEXT
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_apr_human  ON agent_permission_requests(human_id, status)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_apr_status ON agent_permission_requests(status, expires_at)`);
+}
 /**
  * RFC-020 PR-C1 — agent pairing sessions (OAuth device-flow + PKCE shape).
  *
@@ -1812,7 +1866,7 @@ export function initAgentPairingSchema(db) {
       agent_pubkey    TEXT,                             -- RESERVED (PoP); stored if sent, NOT verified in C1
       reason          TEXT,                             -- agent free-text reason (shown in consent)
       capabilities    TEXT NOT NULL DEFAULT '[]',       -- requested SAFE scopes (validated safe-only at start)
-      status          TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | consumed | expired | revoked
+      status          TEXT NOT NULL DEFAULT 'pending',  -- pending | approved | consumed | expired | revoked | rejected(human declined)
       human_id        TEXT,                             -- set on approve
       grant_id        TEXT,                             -- set on approve (issued grant; token_hash filled at retrieve)
       created_at      TEXT NOT NULL DEFAULT (datetime('now')),

package/dist/sale-regions.js

@@ -0,0 +1,116 @@
+const REGION_RE = /^[A-Z0-9-]{2,8}$/;
+/** parse-don't-validate:坏 JSON/坏形状 → null(= 不限,fail-open 到原行为;写入侧另有严校验)。 */
+export function parseSaleRegionsRule(raw) {
+    if (typeof raw !== 'string' || !raw)
+        return null;
+    try {
+        const r = JSON.parse(raw);
+        if (!r || (r.mode !== 'all' && r.mode !== 'list'))
+            return null;
+        const norm = (a) => Array.isArray(a) ? a.map(x => String(x).toUpperCase()).filter(x => REGION_RE.test(x)) : undefined;
+        return { mode: r.mode, include: norm(r.include), exclude: norm(r.exclude) };
+    }
+    catch {
+        return null;
+    }
+}
+/** 写入侧严校验:返回规范化 JSON 串,或 {error}。null/空 = 清除(继承上层)。 */
+export function validateSaleRegionsInput(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { json: null };
+    const r = raw;
+    if (typeof r !== 'object' || (r.mode !== 'all' && r.mode !== 'list'))
+        return { error: "sale_regions.mode 必须是 'all' 或 'list'" };
+    const norm = (a, name) => {
+        if (a === undefined || a === null)
+            return undefined;
+        if (!Array.isArray(a) || a.length > 64)
+            return { error: `sale_regions.${name} 须为 ≤64 项数组` };
+        const out = [];
+        for (const x of a) {
+            const code = String(x).trim().toUpperCase();
+            if (!REGION_RE.test(code))
+                return { error: `sale_regions.${name} 含非法地区码:${String(x).slice(0, 12)}(2-8 位大写字母/数字/-)` };
+            out.push(code);
+        }
+        return [...new Set(out)];
+    };
+    const inc = norm(r.include, 'include');
+    if (inc && 'error' in inc)
+        return inc;
+    const exc = norm(r.exclude, 'exclude');
+    if (exc && 'error' in exc)
+        return exc;
+    if (r.mode === 'list' && (!inc || inc.length === 0))
+        return { error: "mode='list' 时 include 不能为空(否则等于全不可卖 —— 想全不可卖请直接下架)" };
+    return { json: JSON.stringify({ mode: r.mode, ...(inc ? { include: inc } : {}), ...(exc ? { exclude: exc } : {}) }) };
+}
+/** 生效规则:商品 ?? 店铺(与 accept_mode/运费模板同层级约定)。 */
+export function effectiveSaleRegionsRule(db, product, sellerId) {
+    const own = parseSaleRegionsRule(product.sale_regions);
+    if (own)
+        return own;
+    try {
+        const row = db.prepare('SELECT store_sale_regions FROM users WHERE id = ?').get(sellerId);
+        return parseSaleRegionsRule(row?.store_sale_regions);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 平台合规名单解析(单一真相源:建单门 gateSaleRegionForCreate + S5 预检 shipping-options 共用)。
+ *   坏配置(非 JSON / 非数组)→ { ok:false },由调用方 fail-closed(建单 503;预检 sellable=platform_policy_invalid)。
+ *   缺省 '[]' → { ok:true, list:[] }。区码统一大写。
+ */
+export function parsePlatformBlocklist(raw) {
+    try {
+        const p = JSON.parse(String(raw ?? '[]'));
+        if (!Array.isArray(p))
+            return { ok: false };
+        return { ok: true, list: p.map(x => String(x).toUpperCase()) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export function regionAllowedByRule(rule, region) {
+    const r = region.toUpperCase();
+    if (rule.exclude?.includes(r))
+        return false;
+    if (rule.mode === 'list')
+        return !!rule.include?.includes(r);
+    return true;
+}
+/**
+ * 建单可售门(orders-create 单行调用,两轨共用,运费 gate 之前、任何写之前)。
+ * 返回 false = 已写错误响应。平台 overlay 先裁(商家规则不可放宽合规);规则存在但买家没给地区 → fail-closed 要求补选。
+ */
+export function gateSaleRegionForCreate(db, res, product, sellerId, rawRegion, getProtocolParam) {
+    const region = (typeof rawRegion === 'string' && rawRegion.trim()) ? rawRegion.trim().toUpperCase() : null;
+    // ① 平台合规 overlay(protocol param,DEFAULT_PARAMS 已 seed '[]';admin PATCH 有 JSON+区码校验)。
+    //   坏配置【fail-closed】:合规名单读不懂时放行 = 静默解除平台禁售(审计 P2) —— 宁可挡单也不裸奔;
+    //   admin 写入侧已强校验,坏值只可能来自手改 DB,错误信息直接指路。
+    const parsedBlock = parsePlatformBlocklist(getProtocolParam('trade.platform_region_blocklist', '[]'));
+    if (!parsedBlock.ok) {
+        res.status(503).json({ error: '平台合规配置异常,暂无法下单(运营侧需修复 trade.platform_region_blocklist 参数)', error_code: 'PLATFORM_REGION_POLICY_INVALID' });
+        return false;
+    }
+    const platformBlock = parsedBlock.list;
+    const rule = effectiveSaleRegionsRule(db, product, sellerId);
+    if (platformBlock.length === 0 && !rule)
+        return true; // 无任何限制 = 原行为(地区可选)
+    if (!region) {
+        res.status(400).json({ error: '该商品设有可售地区限制,请选择收货国家/地区', error_code: 'SHIP_REGION_REQUIRED' });
+        return false;
+    }
+    if (platformBlock.includes(region)) {
+        res.status(409).json({ error: '平台合规限制:该商品暂不支持销售到该地区', error_code: 'PRODUCT_RESTRICTED', region });
+        return false;
+    }
+    if (rule && !regionAllowedByRule(rule, region)) {
+        res.status(409).json({ error: '卖家未将该地区设为可售范围(与运费无关,不适用询价)', error_code: 'REGION_NOT_FOR_SALE', region });
+        return false;
+    }
+    return true;
+}

package/dist/shipping-templates.js

@@ -0,0 +1,119 @@
+import { toUnits } from './money.js';
+import { freeShippingWaives } from './free-shipping.js'; // 营销域:满额免邮(S2 返工 —— 促销语义不进成本模板)
+const MAX_ENTRIES = 50;
+const MAX_REGION_LEN = 16;
+const MAX_EST_LEN = 20;
+const MAX_FEE = 1_000_000;
+/** 规范化地区 code:trim + 大写。空/非串 → null。 */
+export function normalizeRegion(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const r = raw.trim().toUpperCase();
+    if (!r || r.length > MAX_REGION_LEN)
+        return null;
+    return r;
+}
+/** 校验并规范化模板。null/undefined = 清除模板(合法)。返回 {ok, entries} 或 {ok:false, error}。 */
+export function parseShippingTemplate(raw) {
+    if (raw == null)
+        return { ok: true, entries: null };
+    if (!Array.isArray(raw))
+        return { ok: false, error: '模板必须是数组' };
+    if (raw.length === 0)
+        return { ok: true, entries: null }; // 空数组视同清除
+    if (raw.length > MAX_ENTRIES)
+        return { ok: false, error: `模板最多 ${MAX_ENTRIES} 条` };
+    const out = [];
+    const seen = new Set();
+    for (const e of raw) {
+        const region = e && e.region === '*' ? '*' : normalizeRegion(e?.region);
+        if (!region)
+            return { ok: false, error: '每条须有合法 region(≤16 字大写 code 或 *)' };
+        if (seen.has(region))
+            return { ok: false, error: `region 重复:${region}` };
+        seen.add(region);
+        const fee = Number(e?.fee);
+        if (!Number.isFinite(fee) || fee < 0 || fee > MAX_FEE)
+            return { ok: false, error: `运费必须是 0~${MAX_FEE} 的数字(${region})` };
+        const est = e?.est_days == null ? undefined : String(e.est_days).trim().slice(0, MAX_EST_LEN);
+        out.push({ region, fee: Math.round(fee * 100) / 100, ...(est ? { est_days: est } : {}) });
+    }
+    return { ok: true, entries: out };
+}
+/** 解析已存 JSON(容错:坏 JSON/坏结构 → null=无模板,不阻断读路径)。 */
+export function loadTemplateJson(json) {
+    if (!json)
+        return null;
+    try {
+        const p = parseShippingTemplate(JSON.parse(json));
+        return p.ok ? p.entries : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 生效模板:单品覆盖 ?? 店铺默认 ?? null。product 传订单路径已取到的行(含 shipping_template 列)。 */
+export function effectiveShippingTemplate(db, product, sellerId) {
+    const own = loadTemplateJson(product.shipping_template);
+    if (own)
+        return own;
+    try {
+        const row = db.prepare('SELECT store_shipping_template FROM users WHERE id = ?').get(sellerId);
+        return loadTemplateJson(row?.store_shipping_template);
+    }
+    catch {
+        return null;
+    }
+}
+/** 按买家地区解析运费:精确 → '*' → 未覆盖。(纯成本结构;营销免邮在 gate 层应用) */
+export function resolveShipping(entries, region) {
+    const hit = entries.find(e => e.region === region) ?? entries.find(e => e.region === '*');
+    if (!hit)
+        return { covered: false, fee: 0, est_days: null, matched: null };
+    return { covered: true, fee: hit.fee, est_days: hit.est_days ?? null, matched: hit.region === region ? 'exact' : 'wildcard' };
+}
+/** 询价 opt-in(PR-3):单品 shipping_quote_ok ?? 店铺 store_shipping_quote_ok ?? 关。 */
+export function quoteOutsideTemplateOk(db, product, sellerId) {
+    if (product.shipping_quote_ok != null)
+        return Number(product.shipping_quote_ok) === 1;
+    try {
+        const row = db.prepare('SELECT store_shipping_quote_ok FROM users WHERE id = ?').get(sellerId);
+        return Number(row?.store_shipping_quote_ok) === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 建单运费守门(orders-create 单行调用,两轨共用,任何 DB write 之前):
+ *  - 无模板:不要求地区(给了就规范化快照),运费 0 —— 原行为。
+ *  - 有模板:必须给合法 ship_to_region(否则 400 SHIP_REGION_REQUIRED);命中 → 返回运费(调用方并入总额)。
+ *  - 未命中(含无 '*'):卖家开了询价(quoteOutsideTemplateOk)且直付轨 → quoteRequired=true(建单落
+ *    pending_accept,卖家先报运费/时效、买家确认新总额才进付款窗 —— PR-3);否则(未开询价 / escrow 轨,
+ *    escrow 询价需付款后置钱路手术,PR-5)→ 409 SHIP_REGION_NOT_COVERED。
+ * 返回 null = 已写错误响应,调用方直接 return。
+ */
+export function gateShippingForCreate(db, res, product, sellerId, rawRegion, rail = 'escrow', goodsSubtotalU) {
+    const region = normalizeRegion(rawRegion);
+    const tpl = effectiveShippingTemplate(db, product, sellerId);
+    if (!tpl)
+        return { feeU: 0, fee: 0, region, estDays: null, quoteRequired: false };
+    if (!region) {
+        res.status(400).json({ error: '该商品按地区计运费,请选择收货国家/地区', error_code: 'SHIP_REGION_REQUIRED' });
+        return null;
+    }
+    const r = resolveShipping(tpl, region);
+    if (r.covered) {
+        // 营销域满额免邮(S2 返工:规则在 free-shipping.ts,不在模板)—— 模板费为正 + 券后货款达标 → 免为 0。
+        //   人工询价路径不经此分支(quoteRequired 在下方),天然豁免。
+        if (r.fee > 0 && goodsSubtotalU !== undefined && freeShippingWaives(db, product, sellerId, goodsSubtotalU)) {
+            return { feeU: 0, fee: 0, region, estDays: r.est_days, quoteRequired: false, freeThresholdApplied: true };
+        }
+        return { feeU: toUnits(r.fee), fee: r.fee, region, estDays: r.est_days, quoteRequired: false };
+    }
+    if (rail === 'direct_p2p' && quoteOutsideTemplateOk(db, product, sellerId)) {
+        return { feeU: 0, fee: 0, region, estDays: null, quoteRequired: true }; // 运费待卖家报价,先不入总额
+    }
+    res.status(409).json({ error: rail === 'direct_p2p' ? '卖家暂不配送到该地区' : '卖家暂不配送到该地区(该商品支持直付询价的话,可改用直付下单)', error_code: 'SHIP_REGION_NOT_COVERED', region });
+    return null;
+}

package/dist/trade-tax.js

@@ -0,0 +1,99 @@
+/**
+ * 跨境税费/进口责任【声明+披露】层(S3)—— 卖家 seller-of-record 自我声明,平台【绝不计算/代收/代缴】。
+ *
+ * 定位纪律(调研结论,2026-07):非托管≠必然免平台义务。EU Art.14a "deemed supplier" 的免责是三肢连接测试
+ *   (不设条款 且 不授权收款 且 不涉订单/配送),WebAZ 设条款+涉订单 → 极可能被认定;US CA/WA 型 "any-activity"
+ *   测试里"传递要约/承诺+接单+上架"各自独立触发,与是否碰钱无关。故本层【只声明只披露】,不碰税款:
+ *     - import_duty_terms(DDP/DDU):卖家声明谁承担进口关税/税(DDP=卖家已含于价;DDU=买家到境自付)。
+ *     - tax_lines(仅 'included' 类):卖家声明"价内已含 X 税"(如 SG GST 9%)—— 纯信息披露,不改总额、不入钱路。
+ *   刻意【不做】(不上假开关):'added' 类税进总额(钱路,单独 PR 门控真实需求)、自动税率、代收代缴(Rail 3+律师)。
+ *   合规义务(即便非 deemed):EU 10 年 / UK 6 年交易留痕由 orders.trade_terms_snapshot 满足(S0 已冻结卖家/货/值/时地/单号)。
+ *   跨境进高执法辖区(EU/UK 及 CA/WA 型州)的 deemed-supplier 姿态 → 由 S1 的 trade.platform_region_blocklist 治理门
+ *   + 律师确认逐区放行(本层不自动放开)。详 docs/COMPLIANCE-CROSS-BORDER-TAX.INTERNAL.md。
+ *
+ * 层级:products.{import_duty_terms,tax_lines} ?? users.store_{import_duty_terms,tax_lines}(与接单/运费/可售同约定)。
+ * 快照:S0 的 trade-terms declarations.{import_duty_terms,tax_lines} 已从这些列自动填充 —— 本模块只管写入校验+生效解析+披露。
+ */
+const REGION_RE = /^[A-Z0-9-]{2,8}$/;
+/** DDP/DDU 写入校验:null/空=清除(继承上层);'ddu'|'ddp' 合法。 */
+export function validateImportDutyTerms(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { value: null };
+    if (raw === 'ddu' || raw === 'ddp')
+        return { value: raw };
+    return { error: "import_duty_terms 必须是 'ddu'(买家到境自付)或 'ddp'(卖家已含)或 null" };
+}
+/** 税费科目写入校验:S3 只收 'included'(价内已含,纯披露)。'added'(进总额)明确拒 —— 钱路未开,不上假开关。 */
+export function validateTaxLines(raw) {
+    if (raw === null || raw === undefined || raw === '')
+        return { value: null };
+    if (!Array.isArray(raw))
+        return { error: 'tax_lines 必须是数组或 null' };
+    if (raw.length > 32)
+        return { error: 'tax_lines 最多 32 条' };
+    const out = [];
+    const seen = new Set();
+    for (const e of raw) {
+        if (!e || typeof e !== 'object')
+            return { error: 'tax_lines 每条须是对象' };
+        const r = e;
+        if (r.kind !== undefined && r.kind !== 'included') { // 省略 kind = 'included'(S3 唯一允许值);未来开 'added' 钱路时须显式,勿继承此静默默认
+            return { error: r.kind === 'added' ? "'added' 税费(进总额)暂不支持 —— 平台不代收税;仅支持 'included'(价内已含,披露)" : "tax_lines.kind 仅支持 'included'" };
+        }
+        const region = r.region === '*' ? '*' : (typeof r.region === 'string' ? r.region.trim().toUpperCase() : '');
+        if (region !== '*' && !REGION_RE.test(region))
+            return { error: `tax_lines 含非法 region:${String(r.region).slice(0, 12)}(2-8 位大写码或 *)` };
+        if (seen.has(region))
+            return { error: `tax_lines region 重复:${region}` };
+        seen.add(region);
+        const label = typeof r.label === 'string' ? r.label.trim().slice(0, 40) : '';
+        if (!label)
+            return { error: `tax_lines 每条须有 label(≤40 字,如 GST / VAT)(${region})` };
+        let rate_pct;
+        if (r.rate_pct !== undefined && r.rate_pct !== null) {
+            if (typeof r.rate_pct !== 'number' && typeof r.rate_pct !== 'string')
+                return { error: `tax_lines.rate_pct 必须是数字(${region})` }; // 审计:拒 Number(true)=1 类强转
+            const n = Number(r.rate_pct);
+            if (!Number.isFinite(n) || n < 0 || n > 100)
+                return { error: `tax_lines.rate_pct 必须是 0~100(${region})` };
+            rate_pct = Math.round(n * 100) / 100;
+        }
+        const note = typeof r.note === 'string' && r.note.trim() ? r.note.trim().slice(0, 80) : undefined;
+        out.push({ region, label, ...(rate_pct !== undefined ? { rate_pct } : {}), ...(note ? { note } : {}), kind: 'included' });
+    }
+    return { value: JSON.stringify(out) };
+}
+/** parse-don't-validate 读:坏 JSON/坏形状 → null。 */
+export function parseTaxLines(raw) {
+    if (typeof raw !== 'string' || !raw)
+        return null;
+    try {
+        const a = JSON.parse(raw);
+        if (!Array.isArray(a))
+            return null;
+        return a.filter((e) => !!e && typeof e === 'object' && typeof e.region === 'string' && typeof e.label === 'string');
+    }
+    catch {
+        return null;
+    }
+}
+/** 生效 DDP/DDU:商品 ?? 店铺 ?? null(纯函数;product/store 值由调用方各自的 DB seam 取好传入 —— 消费方是 async seam 路由,不持 sync db)。 */
+export function effectiveImportDutyTerms(productVal, storeVal) {
+    const norm = (x) => (x === 'ddu' || x === 'ddp') ? x : null;
+    return norm(productVal) ?? norm(storeVal);
+}
+/** 生效税费科目:商品 ?? 店铺 ?? null。 */
+export function effectiveTaxLines(productVal, storeVal) {
+    const own = parseTaxLines(productVal);
+    if (own && own.length)
+        return own;
+    const st = parseTaxLines(storeVal);
+    return (st && st.length) ? st : null;
+}
+/** 按目的区筛生效税费(精确 region → '*' 兜底,合并;披露用)。 */
+export function taxLinesForRegion(lines, region) {
+    if (!lines)
+        return [];
+    const r = (region || '').toUpperCase();
+    return lines.filter(l => l.region === '*' || (r && l.region === r));
+}

package/dist/trade-terms.js

@@ -0,0 +1,76 @@
+/** 组装快照(读商品行 + 店铺兜底;shipping 由建单 gate 结果传入 —— 不重算,记录裁决结果)。 */
+export function buildTradeTermsSnapshot(db, args) {
+    // fail-soft 读:缺列(裸测试库/schema 漂移)→ 降级为空槽快照,绝不让证据采集炸掉建单
+    let p;
+    let u;
+    try {
+        p = db.prepare(`SELECT handling_hours, estimated_days, return_days, return_condition, warranty_days,
+      weight_kg, package_size, origin_country, country_of_origin, customs_description, hs_code,
+      ship_regions, sale_regions, tax_lines, import_duty_terms FROM products WHERE id = ?`).get(args.productId);
+        u = db.prepare('SELECT store_sale_regions, store_tax_lines, store_import_duty_terms FROM users WHERE id = ?')
+            .get(args.sellerId);
+    }
+    catch { /* 空槽降级 */ }
+    const parse = (x) => { if (typeof x !== 'string' || !x)
+        return null; try {
+        return JSON.parse(x);
+    }
+    catch {
+        return null;
+    } };
+    const numOrNull = (x) => (x === null || x === undefined || x === '' ? null : Number(x));
+    const strOrNull = (x) => (typeof x === 'string' && x !== '' ? x : null);
+    const duty = strOrNull(p?.import_duty_terms) ?? strOrNull(u?.store_import_duty_terms);
+    return {
+        v: 1,
+        captured_at: new Date().toISOString(),
+        shipping: { source: args.shipping.source, region: args.shipping.region, fee: args.shipping.fee, est_days: args.shipping.estDays, ...(args.shipping.freeThresholdApplied ? { free_threshold_applied: true } : {}) },
+        fulfilment: {
+            handling_hours: numOrNull(p?.handling_hours), estimated_days: strOrNull(p?.estimated_days),
+            return_days: numOrNull(p?.return_days), return_condition: strOrNull(p?.return_condition), warranty_days: numOrNull(p?.warranty_days),
+        },
+        logistics: {
+            weight_kg: numOrNull(p?.weight_kg), package_size: strOrNull(p?.package_size),
+            origin_country: strOrNull(p?.origin_country), country_of_origin: strOrNull(p?.country_of_origin),
+            customs_description: strOrNull(p?.customs_description), hs_code: strOrNull(p?.hs_code),
+        },
+        declarations: {
+            ship_regions_text: strOrNull(p?.ship_regions),
+            sale_regions_rule: parse(p?.sale_regions) ?? parse(u?.store_sale_regions),
+            tax_lines: parse(p?.tax_lines) ?? parse(u?.store_tax_lines),
+            import_duty_terms: duty === 'ddu' || duty === 'ddp' ? duty : null,
+        },
+        accept_mode: args.acceptModeEffective,
+    };
+}
+/** 写快照(fail-soft:任何异常吞掉不阻断建单 —— 快照缺失=pre-S0 订单同待遇,消费方须容错)。 */
+export function writeTradeTermsSnapshot(db, orderId, snap) {
+    try {
+        db.prepare('UPDATE orders SET trade_terms_snapshot = ? WHERE id = ?').run(JSON.stringify(snap), orderId);
+    }
+    catch { /* fail-soft */ }
+}
+/** 询价确认后补记运费裁决(quote_pending → quote;只动 shipping 槽,其余条款保持下单时冻结值)。 */
+export function updateSnapshotShippingQuote(db, orderId, fee, estDays) {
+    try {
+        const row = db.prepare('SELECT trade_terms_snapshot FROM orders WHERE id = ?').get(orderId);
+        if (!row?.trade_terms_snapshot)
+            return;
+        const snap = JSON.parse(row.trade_terms_snapshot);
+        snap.shipping = { ...snap.shipping, source: 'quote', fee, est_days: estDays };
+        db.prepare('UPDATE orders SET trade_terms_snapshot = ? WHERE id = ?').run(JSON.stringify(snap), orderId);
+    }
+    catch { /* fail-soft */ }
+}
+/** parse-don't-validate 读取(DTO/争议消费方用;坏 JSON/缺失 → null)。 */
+export function readTradeTermsSnapshot(raw) {
+    if (typeof raw !== 'string' || !raw)
+        return null;
+    try {
+        const s = JSON.parse(raw);
+        return s && s.v === 1 ? s : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/version.js

@@ -31,4 +31,4 @@ export const SOFTWARE_VERSION = pkg.version;
  *  safe for agents to ignore. Guarded by tests/test-contract-fingerprint.ts + docs/CONTRACT-LOCK.json.
  *  NB: the fingerprint hashes only §②/§① content; a change to the §④ entry document (e.g. agent_quickstart)
  *  is integrator-observable but NOT fingerprinted, so it must be registered here by hand. */
-export const CONTRACT_VERSION = 8;
+export const CONTRACT_VERSION = 23;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "[PRE-LAUNCH] Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools. ⚠️ Repository currently private until W8 public launch — GitHub links may return 404. See https://webaz.xyz for status.",
   "main": "dist/mcp.js",
   "bin": {
@@ -39,6 +39,7 @@
     "meta-rules:check": "tsx scripts/meta-rules-invariant-check.ts",
     "params:check": "tsx scripts/meta-rule-locked-params-check.ts",
     "preflight": "tsx scripts/preflight.ts",
+    "preflight:push": "npm run check:api-docs-fresh && npm run contract:verify && npm run schema:verify && npm run pg:verify && npm run guard:complexity && npm run guard:pr-constraints && npm run routes:seam-check && npm run check:pwa-syntax && npm run build && echo '✅ preflight:push all green'",
     "test:github-credential": "tsx scripts/test-github-credential.ts",
     "test:github-fetch-adapter": "tsx scripts/test-github-fetch-adapter.ts",
     "test:github-authenticated-read": "tsx scripts/test-github-authenticated-read.ts",
@@ -82,6 +83,11 @@
     "test:mcp-fresh-db-schema": "tsx scripts/test-mcp-fresh-db-schema.ts",
     "test:agent-delegation-grants": "tsx scripts/test-agent-delegation-grants.ts",
     "test:agent-pairing": "tsx scripts/test-agent-pairing.ts",
+    "test:agent-pair-ui": "tsx scripts/test-agent-pair-ui.ts",
+    "test:agent-perm-taxonomy": "tsx scripts/test-agent-perm-taxonomy.ts",
+    "test:agent-permission-requests": "tsx scripts/test-agent-permission-requests.ts",
+    "test:agent-permission-consume": "tsx scripts/test-agent-permission-consume.ts",
+    "test:agent-approvals-ui": "tsx scripts/test-agent-approvals-ui.ts",
     "test:agent-grant-verify": "tsx scripts/test-agent-grant-verify.ts",
     "test:agent-grant-mcp-consume": "tsx scripts/test-agent-grant-mcp-consume.ts",
     "test:connected-agents-read": "tsx scripts/test-connected-agents-read.ts",
@@ -99,7 +105,7 @@
     "test:currency-display": "tsx scripts/test-currency-display.ts",
     "test:currency-schema-flip": "tsx scripts/test-currency-schema-flip.ts",
     "test:proposal-admin-ui": "tsx scripts/test-proposal-admin-ui.ts",
-    "check:pwa-syntax": "node --check src/pwa/public/app.js && node --check src/pwa/public/app-admin.js && node --check src/pwa/public/app-contribution.js && node --check src/pwa/public/app-ai.js && node --check src/pwa/public/app-discover.js && node --check src/pwa/public/app-profile.js && node --check src/pwa/public/app-account.js && node --check src/pwa/public/app-shop.js && node --check src/pwa/public/app-listings.js && node --check src/pwa/public/app-external-links.js && node --check src/pwa/public/app-product-media.js && node --check src/pwa/public/app-create-kinds.js && node --check src/pwa/public/app-price.js && node --check src/pwa/public/app-seller.js && node --check src/pwa/public/app-agents.js && node --check src/pwa/public/app-direct-pay.js && node --check src/pwa/public/app-direct-pay-readiness.js && node --check src/pwa/public/app-direct-pay-deferral.js && node --check src/pwa/public/app-direct-pay-deferral-admin.js && node --check src/pwa/public/app-direct-pay-product-verify.js && node --check src/pwa/public/app-direct-pay-store-verify.js && node --check src/pwa/public/app-direct-pay-compliance.js && node --check src/pwa/public/app-direct-pay-fee-ops.js && node --check src/pwa/public/app-direct-pay-fee-center.js && node --check src/pwa/public/app-direct-pay-accounts.js && node --check src/pwa/public/app-direct-pay-buyer.js && node --check src/pwa/public/app-prelaunch-waz.js && node --check src/pwa/public/app-chat-poll.js && node --check src/pwa/public/i18n.js && node --check src/pwa/public/sw.js",
+    "check:pwa-syntax": "node --check src/pwa/public/app-notif-templates.js && node --check src/pwa/public/app-notif-templates-orders.js && node --check src/pwa/public/app.js && node --check src/pwa/public/app-admin.js && node --check src/pwa/public/app-admin-disputes.js && node --check src/pwa/public/app-contribution.js && node --check src/pwa/public/app-ai.js && node --check src/pwa/public/app-discover.js && node --check src/pwa/public/app-profile.js && node --check src/pwa/public/app-account.js && node --check src/pwa/public/app-shop.js && node --check src/pwa/public/app-listings.js && node --check src/pwa/public/app-external-links.js && node --check src/pwa/public/app-product-media.js && node --check src/pwa/public/app-create-kinds.js && node --check src/pwa/public/app-price.js && node --check src/pwa/public/app-order-labels.js && node --check src/pwa/public/app-seller.js && node --check src/pwa/public/app-agents.js && node --check src/pwa/public/app-agent-pair.js && node --check src/pwa/public/app-agent-approvals.js && node --check src/pwa/public/app-agent-appeal.js && node --check src/pwa/public/app-direct-pay.js && node --check src/pwa/public/app-direct-pay-readiness.js && node --check src/pwa/public/app-direct-pay-deferral.js && node --check src/pwa/public/app-direct-pay-deferral-admin.js && node --check src/pwa/public/app-direct-pay-product-verify.js && node --check src/pwa/public/app-direct-pay-store-verify.js && node --check src/pwa/public/app-direct-pay-compliance.js && node --check src/pwa/public/app-direct-pay-fee-ops.js && node --check src/pwa/public/app-direct-pay-fee-center.js && node --check src/pwa/public/app-direct-pay-sales-report.js && node --check src/pwa/public/app-gmv-rail-split.js && node --check src/pwa/public/app-direct-pay-accounts.js && node --check src/pwa/public/app-direct-pay-buyer.js && node --check src/pwa/public/app-direct-pay-pay.js && node --check src/pwa/public/app-direct-pay-reveal.js && node --check src/pwa/public/app-direct-pay-copy.js && node --check src/pwa/public/app-direct-pay-paymodal.js && node --check src/pwa/public/app-direct-pay-memo.js && node --check src/pwa/public/app-direct-pay-negotiation.js && node --check src/pwa/public/app-direct-pay-cancel-refund.js && node --check src/pwa/public/app-direct-pay-returns.js && node --check src/pwa/public/app-order-accept-ui.js && node --check src/pwa/public/app-order-rail-filter.js && node --check src/pwa/public/app-sale-regions-ui.js && node --check src/pwa/public/app-free-shipping-ui.js && node --check src/pwa/public/app-trade-tax-ui.js && node --check src/pwa/public/app-purchase-terms-ui.js && node --check src/pwa/public/app-listing-commerce-ui.js && node --check src/pwa/public/app-bond-terms-ui.js && node --check src/pwa/public/app-bond-ui.js && node --check src/pwa/public/app-bond-refund-ui.js && node --check src/pwa/public/app-bond-slash-ui.js && node --check src/pwa/public/app-bond-deferral-ui.js && node --check src/pwa/public/app-direct-pay-reconcile.js && node --check src/pwa/public/app-mutual-cancel.js && node --check src/pwa/public/app-dispute-close-ui.js && node --check src/pwa/public/app-order-errors.js && node --check src/pwa/public/app-arbitrator-entry.js && node --check src/pwa/public/app-arbitrator-admin.js && node --check src/pwa/public/app-contribution-hub.js && node --check src/pwa/public/app-platform-receive-accounts.js && node --check src/pwa/public/app-direct-pay-fee-request.js && node --check src/pwa/public/app-direct-pay-fee-requests-admin.js && node --check src/pwa/public/app-direct-pay-fee-history.js && node --check src/pwa/public/app-prelaunch-waz.js && node --check src/pwa/public/app-chat-poll.js && node --check src/pwa/public/app-poll-governor.js && node --check src/pwa/public/i18n.js && node --check src/pwa/public/sw.js",
     "test:create-kinds": "tsx scripts/test-create-kinds.ts",
     "test:secondhand-photo-authenticity": "tsx scripts/test-secondhand-photo-authenticity.ts",
     "test:secondhand-detail-alignment": "tsx scripts/test-secondhand-detail-alignment.ts",
@@ -123,6 +129,9 @@
     "test:direct-receive-deposits": "tsx scripts/test-direct-receive-deposits.ts",
     "test:direct-receive-accounts": "tsx scripts/test-direct-receive-accounts.ts",
     "test:direct-receive-account-endpoints": "tsx scripts/test-direct-receive-account-endpoints.ts",
+    "test:platform-receive-accounts": "tsx scripts/test-platform-receive-accounts.ts",
+    "test:fee-prepay-request": "tsx scripts/test-fee-prepay-request.ts",
+    "test:fee-prepay-review": "tsx scripts/test-fee-prepay-review.ts",
     "test:direct-pay-order-qr": "tsx scripts/test-direct-pay-order-qr.ts",
     "test:direct-pay-order-redaction": "tsx scripts/test-direct-pay-order-redaction.ts",
     "guard:direct-pay-order-reader": "tsx scripts/direct-pay-order-reader-guard.ts",
@@ -132,6 +141,40 @@
     "test:direct-pay-base-bond-entry": "tsx scripts/test-direct-pay-base-bond-entry.ts",
     "test:direct-pay-order-snapshot-schema": "tsx scripts/test-direct-pay-order-snapshot-schema.ts",
     "test:direct-pay-ui": "tsx scripts/test-direct-pay-ui.ts",
+    "test:order-errors": "tsx scripts/test-order-errors.ts",
+    "test:fee-request-history": "tsx scripts/test-fee-request-history.ts",
+    "test:i18n-parity": "tsx scripts/test-i18n-parity.ts",
+    "test:arbitrator-lifecycle": "tsx scripts/test-arbitrator-lifecycle.ts",
+    "test:arbitrator-admin-routes": "tsx scripts/test-arbitrator-admin-routes.ts",
+    "test:arbitrate-human-presence": "tsx scripts/test-arbitrate-human-presence.ts",
+    "test:arbitrate-route-e2e": "tsx scripts/test-arbitrate-route-e2e.ts",
+    "test:dispute-dismiss-negotiation": "tsx scripts/test-dispute-dismiss-negotiation.ts",
+    "test:disputes-read-auth": "tsx scripts/test-disputes-read-auth.ts",
+    "test:admin-dispute-triage": "tsx scripts/test-admin-dispute-triage.ts",
+    "test:orders-read-arbitrator-view": "tsx scripts/test-orders-read-arbitrator-view.ts",
+    "test:orders-rail-filter": "tsx scripts/test-orders-rail-filter.ts",
+    "test:directpay-sales-report": "tsx scripts/test-directpay-sales-report.ts",
+    "test:dashboard-gmv-by-rail": "tsx scripts/test-dashboard-gmv-by-rail.ts",
+    "test:direct-pay-cancel-refund": "tsx scripts/test-direct-pay-cancel-refund.ts",
+    "test:direct-pay-returns": "tsx scripts/test-direct-pay-returns.ts",
+    "test:direct-pay-pending-accept": "tsx scripts/test-direct-pay-pending-accept.ts",
+    "test:shipping-templates": "tsx scripts/test-shipping-templates.ts",
+    "test:shipping-quote": "tsx scripts/test-shipping-quote.ts",
+    "test:order-accept-ui": "tsx scripts/test-order-accept-ui.ts",
+    "test:bond-deposit-flow": "tsx scripts/test-bond-deposit-flow.ts",
+    "test:bond-refund-flow": "tsx scripts/test-bond-refund-flow.ts",
+    "test:bond-slash-flow": "tsx scripts/test-bond-slash-flow.ts",
+    "test:bond-deferral-closure": "tsx scripts/test-bond-deferral-closure.ts",
+    "test:agent-strike-ui": "tsx scripts/test-agent-strike-ui.ts",
+    "test:notif-order-templates": "tsx scripts/test-notif-order-templates.ts",
+    "test:legacy-arbitrator-role-sweep": "tsx scripts/test-legacy-arbitrator-role-sweep.ts",
+    "test:arbitration-entry-frontend": "tsx scripts/test-arbitration-entry-frontend.ts",
+    "test:arbitrator-admin-ui": "tsx scripts/test-arbitrator-admin-ui.ts",
+    "test:webauthn-arbitrator-purposes": "tsx scripts/test-webauthn-arbitrator-purposes.ts",
+    "test:mutual-cancel": "tsx scripts/test-mutual-cancel.ts",
+    "test:mutual-cancel-route": "tsx scripts/test-mutual-cancel-route.ts",
+    "test:contribution-hub": "tsx scripts/test-contribution-hub.ts",
+    "test:evidence-active-recheck": "tsx scripts/test-evidence-active-recheck.ts",
     "test:i18n-labels": "tsx scripts/test-i18n-discover-dispute-labels.ts",
     "test:listing-product-type": "tsx scripts/test-listing-product-type.ts",
     "test:external-links": "tsx scripts/test-product-external-links.ts",
@@ -196,6 +239,20 @@
     "test:pv-kill-switch": "tsx scripts/test-pv-kill-switch.ts",
     "test:pv-settlement-engine": "tsx scripts/test-pv-settlement-engine.ts",
     "test:settlement-breakdown": "tsx scripts/test-settlement-breakdown.ts",
+    "test:dispute-noncustodial": "tsx scripts/test-dispute-noncustodial.ts",
+    "test:dispute-settlement-conservation": "tsx tests/test-dispute-settlement-conservation.ts",
+    "test:payment-query-transitions": "tsx scripts/test-payment-query-transitions.ts",
+    "test:payment-query-actions": "tsx scripts/test-payment-query-actions.ts",
+    "test:dispute-withdraw-confirm": "tsx scripts/test-dispute-withdraw-confirm.ts",
+    "test:poll-governor": "tsx scripts/test-poll-governor.ts",
+    "test:role-ui-consistency": "tsx scripts/test-role-ui-consistency.ts",
+    "test:role-switch-guard": "tsx scripts/test-role-switch-guard.ts",
+    "test:trade-terms-snapshot": "tsx scripts/test-trade-terms-snapshot.ts",
+    "test:sale-regions": "tsx scripts/test-sale-regions.ts",
+    "test:trade-tax": "tsx scripts/test-trade-tax.ts",
+    "test:listing-commerce": "tsx scripts/test-listing-commerce.ts",
+    "test:shipping-free-threshold": "tsx scripts/test-shipping-free-threshold.ts",
+    "test:purchase-terms": "tsx scripts/test-purchase-terms.ts",
     "lint:secrets": "gitleaks detect --no-banner --redact --config .gitleaks.toml --exit-code 1",
     "test:wallet-signer": "tsx scripts/test-wallet-signer.ts",
     "test:cf-origin-guard": "tsx scripts/test-cf-origin-guard.ts"