@seasonkoh/webaz 0.1.28 → 0.1.30

package/dist/pwa/acp-feed.js

@@ -1,3 +1,4 @@
+import { displayCurrency } from '../currency.js'; // agent-facing 币种统一 WAZ,遗留 'DCP' 读时归一化(绝不外泄 DCP)
 const BASE = 'https://webaz.xyz';
 // ACP availability 枚举(spec):in_stock | out_of_stock | pre_order | backorder | unknown
 function availability(stock) {
@@ -55,7 +56,7 @@ export function buildAcpProductFeed(db, opts = {}) {
             description: plainText(p.description, 5000), // spec: plain text, max 5000
             url: `${BASE}/#order-product/${p.id}`, // 商品详情页(SPA hash,200)
             // price: spec = Number + ISO 4217 code。WAZ 非 ISO 4217 → 见 feed 级 _disclosures.currency
-            price: { amount: Number(p.price), currency: p.currency || 'WAZ' },
+            price: { amount: Number(p.price), currency: displayCurrency(p.currency) },
             availability: availability(p.stock),
             is_digital: p.product_type === 'digital',
             seller_name: (p.seller_name || p.seller_id).slice(0, 70),
@@ -106,7 +107,7 @@ export function buildAcpProductFeed(db, opts = {}) {
         },
         _disclosures: {
             phase: 'pre-launch',
-            currency: "Each item's price.currency is the protocol's SIMULATED pre-launch internal unit (WAZ, or legacy 'DCP'), NOT an ISO 4217 fiat currency. No real money is involved.",
+            currency: "Each item's price.currency is the protocol's SIMULATED pre-launch internal unit, always emitted as WAZ (legacy internal-code rows are normalized to WAZ on read), NOT an ISO 4217 fiat currency. No real money is involved.",
             checkout: 'is_eligible_checkout is false for every item: ACP checkout is not yet wired. Products are DISCOVERABLE via ACP, not yet PURCHASABLE via ACP. Native WebAZ checkout + escrow + state machine govern real purchases (see RFC-015).',
         },
         product_count: products.length,

package/dist/pwa/arbitration-read-admin.js

@@ -0,0 +1,37 @@
+/**
+ * 争议详情【只读】admin 授权谓词 —— 与后台列表 /api/admin/disputes 的 requireArbitrationAdmin
+ * (= requireAdminPermission(req,res,'arbitration'))【等价】的纯布尔判定(不发响应,可在 guard 里与其他条件组合)。
+ *
+ * 单一真相源:server.ts 注册 disputes-read、以及 test-disputes-read-auth 都用它 → 后台列表与详情页授权一致,
+ * 不会出现"能进列表却进不了详情"(错挡)或"没 arbitration 权限却能直读详情"(错放)。
+ *
+ * 规则(镜像 server.ts 的 requireAdmin + hasAdminPermission,见 server.ts:3739/3765):
+ *   1. 必须是 admin:user.role === 'admin' 或 roles 数组含 'admin'(grant-role 只把 admin 加进 roles,不改主 role)。
+ *   2. 且具 arbitration 权限:root admin(admin_type 缺省视为 'root')隐式拥有 all;区域 admin 看 admin_permissions
+ *      是否含 'all' 或 'arbitration'。
+ * 注意:isRoot 用 admin_type ?? 'root' —— 非 admin 用户 admin_type 为 NULL 会被当 root,所以【必须】先过第 1 步 admin 门,
+ *   否则普通 buyer 会被误判为 root(与 server.ts 先 requireAdmin 再 hasAdminPermission 的顺序一致)。
+ */
+export function isArbitrationReadAdmin(user) {
+    if (!user)
+        return false;
+    const roles = (() => { try {
+        return JSON.parse(user.roles || '[]');
+    }
+    catch {
+        return [];
+    } })();
+    const isAdmin = user.role === 'admin' || (Array.isArray(roles) && roles.includes('admin'));
+    if (!isAdmin)
+        return false;
+    const isRoot = (user.admin_type || 'root') === 'root';
+    if (isRoot)
+        return true;
+    const perms = (() => { try {
+        return JSON.parse(user.admin_permissions || '[]');
+    }
+    catch {
+        return [];
+    } })();
+    return Array.isArray(perms) && (perms.includes('all') || perms.includes('arbitration'));
+}

package/dist/pwa/arbitrator-lifecycle.js

@@ -0,0 +1,100 @@
+const SYSTEM_ACCOUNT_IDS = new Set(['sys_protocol', 'usr_iaudit_001']);
+const effectiveStatus = (row) => !row ? null : (row.status ?? 'active'); // legacy NULL = active
+/** 仲裁资格:唯一看 active arbitrator_whitelist。role='arbitrator' 不再是旁路。 */
+export function isEligibleArbitrator(db, userId) {
+    const st = effectiveStatus(db.prepare('SELECT status FROM arbitrator_whitelist WHERE user_id = ?').get(userId));
+    if (st === null)
+        return { ok: false, reason: '非仲裁员 — 需 active arbitrator_whitelist(role 不再作旁路)' };
+    if (st === 'active')
+        return { ok: true, via: 'whitelist' };
+    return { ok: false, reason: st === 'suspended' ? '仲裁员资格已暂停' : '仲裁员资格已撤销' };
+}
+/** 目标必须是可授权的真实人类:非系统/内部号、非 system 角色、已注册 Passkey。 */
+function assertGrantableHuman(db, userId) {
+    if (SYSTEM_ACCOUNT_IDS.has(userId))
+        return { ok: false, error_code: 'NOT_HUMAN', error: '系统/内部账号不可授权为仲裁员' };
+    const u = db.prepare('SELECT id, role, roles FROM users WHERE id = ?').get(userId);
+    if (!u)
+        return { ok: false, error_code: 'USER_NOT_FOUND', error: '用户不存在' };
+    let roles = [];
+    try {
+        roles = JSON.parse(u.roles || '[]');
+    }
+    catch { }
+    // 拒 system 与 agent(即便有 Passkey):agent 是程序化行为体,仲裁是真人铁律节点。
+    if (u.role === 'system' || u.role === 'agent' || roles.includes('system') || roles.includes('agent')) {
+        return { ok: false, error_code: 'NOT_HUMAN', error: 'system/agent 账号不可授权为仲裁员' };
+    }
+    const hasPk = db.prepare('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?').get(userId).n > 0;
+    if (!hasPk)
+        return { ok: false, error_code: 'PASSKEY_REQUIRED', error: '目标需先注册 Passkey(仲裁需真人);合成/agent 账号无 Passkey 故被拒' };
+    return null;
+}
+/** 授权为 active 仲裁员。revoked 终态不可复活。 */
+/** 授权核心【无事务包裹】—— 调用方(approve / governance activate)可在自己的 db.transaction 内与状态翻转
+ *   同事务调用,失败时一起回滚(P2-2:grant 与申请/治理状态翻转原子)。只写不开事务;失败不写。 */
+export function grantArbitratorTx(db, p) {
+    const bad = assertGrantableHuman(db, p.userId);
+    if (bad)
+        return bad;
+    const st = effectiveStatus(db.prepare('SELECT status FROM arbitrator_whitelist WHERE user_id = ?').get(p.userId));
+    if (st === 'revoked')
+        return { ok: false, error_code: 'REVOKED_TERMINAL', error: '该用户已被永久撤销仲裁员资格,不可重新授权' };
+    if (st === null) {
+        db.prepare("INSERT INTO arbitrator_whitelist (user_id, note, is_system, granted_by, status) VALUES (?,?,0,?, 'active')").run(p.userId, p.note ?? '管理员直接授权', p.grantedBy);
+    }
+    else {
+        db.prepare("UPDATE arbitrator_whitelist SET status='active', granted_by=?, note=?, suspended_at=NULL WHERE user_id=? AND status != 'revoked'").run(p.grantedBy, p.note ?? '管理员直接授权', p.userId);
+    }
+    return { ok: true };
+}
+/** 独立授权(direct grant):把核心包进自己的事务。approve/governance 请改用 grantArbitratorTx 与状态翻转同事务。 */
+export function grantArbitrator(db, p) {
+    let out = { ok: true };
+    db.transaction(() => { out = grantArbitratorTx(db, p); })();
+    return out;
+}
+/** 暂停(可逆)。revoked 不可暂停。 */
+export function suspendArbitrator(db, p) {
+    const st = effectiveStatus(db.prepare('SELECT status FROM arbitrator_whitelist WHERE user_id = ?').get(p.userId));
+    if (st === null)
+        return { ok: false, error_code: 'NOT_ARBITRATOR', error: '该用户不是仲裁员' };
+    if (st === 'revoked')
+        return { ok: false, error_code: 'REVOKED_TERMINAL', error: '已永久撤销,不可暂停' };
+    db.prepare("UPDATE arbitrator_whitelist SET status='suspended', suspended_at=datetime('now') WHERE user_id=? AND status != 'revoked'").run(p.userId);
+    return { ok: true };
+}
+/** 复用(暂停→active)。revoked 终态不可复活。 */
+export function reinstateArbitrator(db, p) {
+    const st = effectiveStatus(db.prepare('SELECT status FROM arbitrator_whitelist WHERE user_id = ?').get(p.userId));
+    if (st === null)
+        return { ok: false, error_code: 'NOT_ARBITRATOR', error: '该用户不是仲裁员' };
+    if (st === 'revoked')
+        return { ok: false, error_code: 'REVOKED_TERMINAL', error: '已永久撤销,不可复用' };
+    if (st === 'active')
+        return { ok: false, error_code: 'ALREADY_ACTIVE', error: '仲裁员已是 active' };
+    db.prepare("UPDATE arbitrator_whitelist SET status='active', suspended_at=NULL WHERE user_id=? AND status='suspended'").run(p.userId);
+    return { ok: true };
+}
+/** 撤销(终态,不可逆)。active/suspended 均可撤销;已撤销幂等。 */
+export function revokeArbitrator(db, p) {
+    const st = effectiveStatus(db.prepare('SELECT status FROM arbitrator_whitelist WHERE user_id = ?').get(p.userId));
+    if (st === null)
+        return { ok: false, error_code: 'NOT_ARBITRATOR', error: '该用户不是仲裁员' };
+    if (st === 'revoked')
+        return { ok: true }; // 幂等:已终态
+    db.prepare("UPDATE arbitrator_whitelist SET status='revoked', revoked_at=datetime('now') WHERE user_id=?").run(p.userId);
+    return { ok: true };
+}
+/** 名册(admin 只读)。status NULL 归一为 active 便于展示。 */
+export function listArbitrators(db) {
+    const rows = db.prepare(`SELECT user_id, status, added_at, suspended_at, revoked_at, granted_by, is_system, note
+    FROM arbitrator_whitelist ORDER BY added_at DESC`).all();
+    return rows.map(r => ({ ...r, status: (r.status ?? 'active') }));
+}
+/** COI:当前用户是否为本案当事方(买家/卖家/物流/发起人/被诉人)→ 不得仲裁。 */
+export function arbitratorHasConflict(db, orderId, initiatorId, defendantId, userId) {
+    const o = db.prepare('SELECT buyer_id, seller_id, logistics_id FROM orders WHERE id = ?').get(orderId);
+    const parties = [o?.buyer_id, o?.seller_id, o?.logistics_id, initiatorId, defendantId];
+    return parties.some(p => p != null && p === userId);
+}

package/dist/pwa/contract-fingerprint.js

@@ -36,6 +36,24 @@ export const CONTRACT_CHANGES = [
     { contract_version: 3, date: '2026-06-09', surface: 'entity', kind: 'changed', summary: '§① order lifecycle: corrected declined_nofault state meaning text — it is NOT terminal (transitions declined_nofault→completed on settlement). Dropped the contradictory "(terminal)" label that conflicted with the auto-derived terminal:false. Semantics/state-machine unchanged; text-only clarification for agents reading the entity dictionary.' },
     { contract_version: 4, date: '2026-06-09', surface: 'capability', kind: 'changed', summary: '§② capability matrix: POST /api/reviews/:type/:id/claim now requires the new "review_claim" action scope instead of being SAFE (unscoped). The review-claim path locks a 5 WAZ stake (escrow), so it belongs under default-deny accountability like other value writes. GET reviews endpoints stay open.', migration: 'A declared agent that calls review claim must add the "review_claim" scope to its api_key (or hold a Passkey, or declare "*"). Passkey-bound humans and "*" agents are unaffected; GET reviews unchanged.' },
     { contract_version: 5, date: '2026-06-24', surface: 'integration', kind: 'added', summary: '§④ integration-contract entry (/.well-known/webaz-integration.json) gains an agent_quickstart block: a 60-second stranger-agent cold-start with discrete, machine-parseable fields (canonical_start_url, public_readonly_entrypoints, anonymous_allowed_actions, authenticated_required_actions, safe_next_actions, proposal_flow, contribution_boundary). Additive — no existing field changed; agents may ignore. NB: this surface is NOT covered by the §②/§① fingerprint, so it is registered here by hand.' },
+    { contract_version: 6, date: '2026-06-27', surface: 'entity', kind: 'added', summary: '§① order lifecycle gains two Direct Pay Rail 1 (non-custodial off-protocol payment) states: direct_pay_window (seller fee-stake locked, payment method shown, awaiting buyer off-protocol payment) and direct_expired_unconfirmed (payment window timed out without buyer confirmation — order is NOT silently closed; buyer retains a dispute/confirm window). Additive — existing order states/transitions unchanged; escrow orders never enter these states; agents may ignore unless they place direct_p2p orders.' },
+    { contract_version: 7, date: '2026-06-27', surface: 'capability', kind: 'added', summary: '§② capability matrix RESERVES a new "direct_pay" action scope for the future /api/direct-pay/* surface (Direct Pay Rail 1). SCAFFOLD ONLY: this revision ships the D1/D2 disclosure helper + append-only ack model and a Passkey RISK-guard helper for later wiring — NO production route is gated yet, and the current order-action paths (mark_paid / cancel / confirm / confirm-in-person) do NOT yet enforce the Passkey or the two-disclosure-ack gate. The classifier maps /api/direct-pay/* → direct_pay so that surface is RISK-scoped the moment routes are added. Additive — no existing action changed.', migration: 'No behavioural change yet — do NOT assume Direct Pay order actions are Passkey-gated or disclosure-gated at this revision, and do NOT assume agents are blocked from them. Real enforcement (Passkey + two-disclosure-ack on mark_paid/confirm/confirm-in-person) is wired in a later PR together with the create route, ack endpoints, and UI.' },
+    { contract_version: 8, date: '2026-07-02', surface: 'capability', kind: 'added', summary: 'Direct Pay Rail 1 (non-custodial) buyer account selection: POST /api/orders now accepts an OPTIONAL direct_receive_account_id — when a seller offers multiple receive accounts (GET /api/direct-receive/selectable-accounts, metadata-only), the buyer picks one and the create route snapshots THAT account. Omitted → unchanged dual-read fallback to the seller\'s single legacy payment instruction (no behaviour change for sellers with only that). The direct_p2p order gains a direct_pay_account_snapshot (non-sensitive metadata {account_id,method,currency,label,qr_ref} frozen at create); the raw instruction text stays in the existing disclosure-gated snapshot. New buyer read GET /api/orders/:id/direct-pay-qr serves the snapshotted receive-QR image bytes, gated to the order buyer AND both D1/D2 disclosure acks (non-enumerating 404 otherwise). Additive — this create-body field + order-metadata snapshot are NOT part of the §②/§① fingerprint projection, so registered here by hand; no existing action or order state changed.', migration: 'Agents placing direct_p2p orders MAY pass direct_receive_account_id (from selectable-accounts) to choose how they pay; omitting it preserves the prior single-instruction behaviour. The raw payment instruction and the QR image remain revealed only after both disclosure acks.' },
+    { contract_version: 9, date: '2026-07-03', surface: 'entity', kind: 'added', summary: '§① order lifecycle gains a Direct Pay Rail 1 (non-custodial) negotiation state payment_query + its transitions (accepted→payment_query, payment_query→{accepted,cancelled,disputed}, disputed→payment_query withdraw). NOW LIVE & ENFORCED (staged PR-A state-machine → PR-B routes + timing → PR-C UI, all shipped on this same v9 surface — the wiring needed no dictionary change): for direct_p2p, seller non-receipt → payment_query = bilateral negotiation (争议) that PRECEDES 举证仲裁, not arbitration-on-first-report. The legacy accepted→disputed "未收到货款" button is RETIRED for direct_p2p (seller now uses report_nonpayment → payment_query). Flow: payment_query→disputed = evidence-required escalation (举证仲裁); confirm-received resume (payment_query→accepted); buyer/seller cancel; a 7-day buyer-recourse window after seller request-cancel; withdraw-before-ruling (disputed→payment_query) — RESTRICTED (route + DTO fail-closed) to disputes that were themselves escalated from payment_query, so fulfilment disputes (delivered→disputed, 货损/货不对版) are NOT withdrawable. Additive — existing states/transitions unchanged; escrow never uses these transitions (route guard enforces direct_p2p-only entry).', migration: 'direct_p2p non-receipt now uses the payment_query negotiation stage — seller 未收到货款 opens bilateral negotiation, NOT immediate arbitration. Legacy accepted→disputed is retired for direct_p2p (escrow-rail disputes unchanged). Agents/integrators: treat payment_query as a live order state; disputed→payment_query withdraw is available only for payment_query-escalated disputes (server returns NOT_PAYMENT_QUERY_DISPUTE otherwise) and can_withdraw_payment_query_dispute on the order DTO signals when it is offered.' },
+    { contract_version: 10, date: '2026-07-03', surface: 'capability', kind: 'added', summary: 'Mutual cancel (协商取消): a no-fault, both-parties-consent way to terminate a DISPUTED order, alongside arbitration. New party-only endpoints POST /api/orders/:id/mutual-cancel/{propose,accept,decline,withdraw} + GET /api/orders/:id/mutual-cancel (current proposal + the caller\'s available actions). Handshake: either party (buyer/seller) proposes; the counterparty accepts → executed atomically (db.transaction). Outcome is NEUTRAL: the order goes to the existing terminal state \'cancelled\' (no new state or transition edge — reuses disputed→cancelled, executed by the protocol on consent), the active dispute is resolved in the SAME tx (verdict=mutual_cancel) so timeout auto-judge cannot double-settle, the buyer is made whole (escrow-rail → full escrow refund + seller stake returned; direct_p2p → zero funds, protocol never held them), and NEITHER party takes any reputation/fault/fee (no dispute_loss_count, no arbitration fee). Because it adds neither an order state/edge (§①) nor a named capability scope (§②), the §②/§① fingerprint is UNCHANGED — registered here by hand. Enforcement: these writes carry NO per-action Passkey / human-presence gate (unlike withdraw / arbitrate / direct-pay actions) — the safeguard is the two-party consent handshake itself (a single compromised session cannot unilaterally cancel, because the counterparty must independently accept). They classify under the generic default-deny \'write\' scope: session-authenticated parties and \'*\' agents may call them; narrow-scope declared agents are default-denied (an order-unwinding money action is not a delegated narrow scope).', migration: 'Agents/integrators: a disputed order can now reach \'cancelled\' via bilateral mutual-cancel consent (not only via arbitration ruling or timeout). Poll GET /api/orders/:id/mutual-cancel for a pending proposal and the caller\'s can_{propose,accept,decline,withdraw} flags. No existing action, order state, or transition changed. Escrow refund on accept touches ONLY funds actually locked for the order: buyer made-whole is FAIL-CLOSED — the buyer\'s real escrowed must be ≥ the order total or the accept aborts with ESCROW_INSUFFICIENT (no partial refund, no close, dispute stays open); seller stake return is best-effort from the order snapshot stake_backing+bid_stake_held (capped to real staked, never the product\'s nominal stake_amount). GET .../mutual-cancel is party-gated (non-party → 403; no proposal/reason leak).' },
+    { contract_version: 11, date: '2026-07-03', surface: 'entity', kind: 'added', summary: '§① order lifecycle: the disputed→payment_query edge gains \'system\' as an allowed actor (was buyer/seller only). This backs a new arbitrator action "dismiss arbitration → back to negotiation" (ruling=dismiss_to_negotiation on POST /api/disputes/:id/arbitrate): an arbitrator may decline to rule winner/loser and instead return a Direct Pay (direct_p2p) payment-query-originated dispute to bilateral negotiation. It is NOT a merit ruling — no refund/liability/settlement, no arbitration fee, no reputation change, no escrow movement. Effect mirrors the party pq_withdraw close: order disputed→payment_query (executed by sys_protocol under the arbitrator\'s live-Passkey authorization + active-whitelist + COI/assignment gates), active dispute→dismissed (ruling_type=dismiss_to_negotiation), payment_query_deadline rebuilt, payment_query_cancel_deadline cleared, both parties notified. RESTRICTED (route + domain fail-closed) to direct_p2p disputes whose most recent entry into disputed was from payment_query — fulfilment disputes (delivered→disputed) and escrow disputes are rejected (NOT_PAYMENT_QUERY_DISPUTE / ARBITRATION_DISMISS_NOT_ALLOWED), so escrow funds are never touched. Additive — no state added, no existing edge/actor removed; the §① entity fingerprint changes only because allowed_roles on this one edge grew.', migration: 'Agents/integrators arbitrating direct_p2p payment-query disputes now have a fifth ruling option dismiss_to_negotiation that returns the order to payment_query instead of ruling. The order DTO / dispute detail expose can_dismiss_to_negotiation to signal when it is offered. Server returns NOT_PAYMENT_QUERY_DISPUTE / ARBITRATION_DISMISS_NOT_ALLOWED for fulfilment/escrow disputes. Like all arbitrate rulings it requires a purpose=\'arbitrate\' WebAuthn gate token bound to the dispute_id.' },
+    { contract_version: 12, date: '2026-07-04', surface: 'entity', kind: 'added', summary: '§① order lifecycle gains an accepted→cancelled edge, allowed actor \'system\' ONLY. This backs the Direct Pay Rail 1 (non-custodial) post-payment cancel-refund handshake: after the buyer has paid off-protocol (mark_paid → accepted) and BEFORE the seller ships, the buyer may request cancellation. Because the protocol never held the buyer\'s money it cannot refund — the refund happens off-protocol and the protocol only orchestrates a three-step handshake via new party-only endpoints POST /api/orders/:id/cancel-refund/{request,decline,mark-refunded,withdraw,confirm} + GET /api/orders/:id/cancel-refund (party-gated state + caller\'s available actions): buyer requests (reason, ≤3 requests/order) → seller either declines (fulfilment continues) or marks refunded (optional refund reference) → buyer confirms the refund arrived (RISK: live-Passkey gate token, purpose=direct_pay_order_action, action=cancel_refund_confirm) → the protocol executes accepted→cancelled atomically (sys actor, db.transaction: request row CAS + transition + stock restore). NEUTRAL outcome: zero funds moved, no fee (fee AR accrues only at completed), no reputation/fault for either side. Buyer withdraw is allowed only BEFORE the seller marks refunded (afterwards the buyer must confirm or open a dispute — otherwise a refunded seller could be left with fulfilment still owed). The handshake does NOT block shipping: if the seller ships while a request is open the handshake goes stale fail-closed (mark-refunded/confirm reject with ORDER_NOT_ACCEPTED). Seller silence past the respond deadline (direct_pay.cancel_refund_respond_days, default 5) lazily expires the request — no auto-cancel (that would presume the refund happened); the buyer may re-request or escalate via the existing accepted→disputed evidence path. Escrow orders are rejected (NOT_DIRECT_PAY) — escrow refunds keep their own semantics; the new edge is system-only so no party can drive accepted→cancelled directly on ANY rail.', migration: 'Agents/integrators: a direct_p2p order in accepted can now reach \'cancelled\' via the bilateral cancel-refund handshake. Poll GET /api/orders/:id/cancel-refund for the open request + can_{request,respond,confirm,withdraw} flags. The confirm step requires a purpose=direct_pay_order_action WebAuthn gate token with purpose_data {order_id, action:\'cancel_refund_confirm\'} — agents cannot perform it (Passkey hard requirement). No existing state/edge/actor changed; escrow orders and all non-handshake paths are unaffected.' },
+    { contract_version: 13, date: '2026-07-04', surface: 'entity', kind: 'added', summary: 'Direct Pay Rail 1: the per-order direct_pay_account_snapshot metadata gains OPTIONAL payable_* fields frozen at order create — payable_usdc (the order total in the platform display unit) and, when the chosen receive account is denominated in a supported non-USD fiat, payable_approx / payable_currency / payable_rate / payable_asof / payable_stale (a DISPLAY-ONLY reference conversion from the cached FX snapshot). Purpose: the buyer pay UI, the mark_paid timeline note (which now records 付款参考 + 应付 amount) and the seller reconciliation all reference ONE stable figure instead of re-converting with a drifting live rate. This is explicitly NOT a settlement quote: the rate may be stale (flagged), the authoritative amount is whatever the seller payment instruction states, and conversion failure simply omits payable_approx (order creation is never blocked). Additive — orders created before this revision lack the fields and clients fall back to live conversion / USDC-only display. Like v8, this snapshot is NOT part of the §②/§① fingerprint, so registered here by hand.', migration: 'Integrators reading direct_pay_account_snapshot may use payable_* when present; treat payable_approx as an at-create reference hint (payable_stale marks a cached/fallback rate), never as a settlement amount. Orders without the fields: convert client-side or show the USDC figure.' },
+    { contract_version: 14, date: '2026-07-04', surface: 'capability', kind: 'changed', summary: 'Direct Pay Rail 1 disclosure acks (POST /api/direct-pay/disclosure-acks): (a) the endpoint now ALSO accepts stage:"both" — a single live-Passkey ceremony (gate token purpose_data.stage="both") records BOTH pre_select + pre_confirm ack rows at once, cutting the buyer\'s first-order Passkey ceremonies from 3 to 2 (the two disclosure SCREENS are still shown and confirmed; only the human-presence proof is consolidated; the two append-only ack rows and requireBothDisclosuresAcked evidence model are unchanged; the separate mark_paid RISK Passkey is unchanged). Existing single-stage POSTs (stage:"pre_select"|"pre_confirm") keep working. (b) The D1/D2 disclosure TEXT was reworded for accuracy ("non-guaranteed / no refund CAPABILITY / seller reputation penalty only" instead of "no refund") and its notice_version bumped d1.v1→d1.v2, d2.v1→d2.v2 — so GET /api/direct-pay/disclosure-acks/:orderId now returns the new text/versions and, for orders acked under v1, acked:{pre_select|pre_confirm}=false until re-acked under v2. recordDisclosureAck changed from INSERT-OR-IGNORE to an upsert so a re-ack under a new version actually refreshes the row (prior behavior would have silently no-op\'d and permanently blocked such orders). Not part of the §②/§① fingerprint (disclosure payload/versioning), registered here by hand.', migration: 'Buyers/integrators: the disclosure-ack POST may send stage:"both" with a purpose_data.stage="both" gate token to satisfy both disclosures in one ceremony; single-stage calls remain valid. After this revision, previously-recorded v1 acks read as un-acked (acked:false) until re-confirmed under d1.v2/d2.v2 — re-acking now works (upsert). No order state/edge/fund path changed; requireBothDisclosuresAcked still hard-gates mark_paid/confirm/confirm-in-person.' },
+    { contract_version: 15, date: '2026-07-04', surface: 'capability', kind: 'added', summary: 'Direct Pay Rail 1 post-delivery RETURNS: direct_p2p orders can now use the standard return flow (POST /api/orders/:id/return-request on a completed order within return_days, seller decide, optional pickup logistics, negotiation messages) — the previous hard block (DIRECT_PAY_NO_REFUND) is REMOVED. Only the REFUND EXECUTION step differs from escrow: because the protocol never held the buyer\'s money, seller acceptance moves the return to a new await_refund status (off-protocol refund owed) instead of an escrow wallet transfer, then two new party-only endpoints complete the handshake — POST /api/return-requests/:id/mark-refunded (seller declares the off-protocol refund, optional refund_reference) → refund_marked, and POST /api/return-requests/:id/confirm-refund (buyer confirms the refund arrived; RISK: live-Passkey gate token purpose=direct_pay_order_action, purpose_data {order_id, action:"return_refund_confirm"}) → refunded (terminal). ZERO funds moved, ZERO automatic stock restore (post-outbound goods require offline inspection before manual restock — deliberate anti-oversell rule), platform fee receivable NOT auto-reversed (admin adjustment path). Escalation: refund_marked → buyer may escalate to dispute anytime (declaration ≠ receipt); await_refund → escalatable after direct_pay.return_refund_respond_days (default 5); the existing rejected / pending≥7d escalations still apply. Order status is NOT changed by a return (same as escrow returns). Full-amount confirmed returns decrement the product\'s best-effort completion_count (authoritative genuine-sale predicate already excludes direct_p2p). Escrow returns are COMPLETELY unchanged. return_requests rows gain refund_reference + await_refund_since columns and the two new statuses await_refund | refund_marked. Not part of the §②/§① fingerprint (no order state/edge/scope change), registered here by hand.', migration: 'Agents/integrators: a completed direct_p2p order now accepts return requests like escrow orders; DIRECT_PAY_NO_REFUND is no longer returned. Track the two new return_request statuses await_refund and refund_marked; the buyer confirm step requires a purpose=direct_pay_order_action WebAuthn gate token with purpose_data {order_id, action:"return_refund_confirm"} — agents cannot perform it (Passkey hard requirement). Do NOT expect stock to be restored or any wallet movement on a direct_p2p return.' },
+    { contract_version: 16, date: '2026-07-04', surface: 'entity', kind: 'added', summary: 'Manual order-acceptance mode (accept_mode): sellers may require MANUAL acceptance before the buyer pays — per-product products.accept_mode overriding a store-wide users.store_accept_mode (effective mode is SNAPSHOT onto the order at create; later setting changes never affect in-flight orders; unset = auto = prior behavior on both rails). §① order lifecycle gains state pending_accept (manual direct_p2p orders land here at create instead of direct_pay_window) + 3 edges: created→pending_accept (system, at create), pending_accept→direct_pay_window (seller accepts — ONLY now does the payment window clock start and the payment instruction/QR become readable; a STATUS gate in the shared redaction projector hides the payment target during pending_accept even if D1/D2 are already acked), pending_accept→cancelled (seller decline / buyer withdraw / system timeout after direct_pay.accept_window_hours, default 24h — a NO-FAULT cancel: nobody has paid, zero funds move, stock restored via the pre-ship restock whitelist, both parties notified). New party-only endpoints POST /api/orders/:id/pending-accept/{accept,decline,cancel} + seller setting POST /api/seller/accept-mode. ESCROW rail deliberately does NOT use pending_accept: escrow is already a conditional intermediate state (funds locked at order, seller must accept within 24h or the buyer is auto-refunded in full) — accept_mode=auto on escrow simply auto-accepts at paid (formalizing the auto_accept Skill), manual/unset keeps todays flow. pending_accept counts toward the per-buyer open-order cap and the sellers in-flight fee estimate (griefing guards). Rationale: a non-custodial rail has no authorization-hold primitive — sequencing (accept before pay) is the only honest payment risk control.', migration: 'Agents placing direct_p2p orders: the create response may now return status pending_accept — do NOT expect payment instructions until the order reaches direct_pay_window (the payment-target fields stay redacted and the QR endpoint 404s during pending_accept). Track the new state + 3 edges from the lifecycle contract. Escrow orders and all orders on sellers/products without accept_mode=manual behave exactly as before.' },
+    { contract_version: 17, date: '2026-07-04', surface: 'capability', kind: 'added', summary: 'Region-based shipping-fee templates: sellers may predefine per-region shipping fees + estimated delivery time — per-product products.shipping_template overriding a store-wide users.store_shipping_template (JSON entries {region (uppercase code or "*" wildcard = rest of world), fee (same unit as the product price), est_days (display-only)}). When an EFFECTIVE template exists for a product, POST /api/orders REQUIRES a new body field ship_to_region (else 400 SHIP_REGION_REQUIRED); a covered region adds the template fee into total_amount BEFORE any money/gate logic on BOTH rails (escrow lock, dp per-tx cap and platform fee all see the fee-inclusive total — same convention as the insurance premium; no separate shipping settlement subject in v1) and snapshots orders.{ship_to_region, shipping_fee, shipping_est_days} (later template edits never affect in-flight orders); an uncovered region REJECTS order creation with 409 SHIP_REGION_NOT_COVERED (a quote-on-accept handshake for uncovered regions ships in a later revision). Products/sellers WITHOUT a template behave exactly as before (ship_to_region optional, no fee). New endpoints: POST /api/seller/shipping-template (seller: store default and/or per-product override; null/[] clears) and public GET /api/products/:id/shipping-options (effective template + region_required flag — buyers can see coverage/fee/ETA before ordering). est_days is display-only and does NOT feed the fulfilment-deadline clocks. Payment timing is UNCHANGED on both rails. Not part of the §②/§① fingerprint (create-body field + non-fingerprinted endpoints), registered by hand.', migration: 'Agents placing orders: call GET /api/products/:id/shipping-options first — if region_required, include ship_to_region (uppercase region code) in POST /api/orders and expect the returned total to include the template shipping fee; handle 400 SHIP_REGION_REQUIRED and 409 SHIP_REGION_NOT_COVERED. Orders on products without a template are unaffected.' },
+    { contract_version: 18, date: '2026-07-04', surface: 'capability', kind: 'added', summary: 'Shipping quote-on-accept handshake (direct_p2p only): when a product has an effective shipping template, the buyer region is NOT covered, and the seller has opted in (products.shipping_quote_ok ?? users.store_shipping_quote_ok, default OFF — settable via POST /api/seller/shipping-template {store_quote_ok | product_id+quote_ok}; surfaced as quote_outside_template on GET /api/products/:id/shipping-options), POST /api/orders no longer 409s: the order is created into pending_accept with shipping_quote_required=1 (REGARDLESS of accept_mode) and ZERO shipping fee in the total. Flow: seller POST /api/orders/:id/pending-accept/quote {shipping_fee, est_days?, note?} — the quote may only ADD a shipping-fee line (goods price untouchable) and goods+fee must fit the per-tx cap SNAPSHOT frozen at create (409 QUOTE_EXCEEDS_CAP — shipping cannot smuggle past the small-amount rail boundary); re-quoting before confirmation is allowed and each quote resets the response window (direct_pay.quote_confirm_hours, default 48h, same pending_accept_deadline → the expiry sweep covers both quote silence and confirm silence). Buyer POST .../confirm-quote → atomically (one db.transaction) total_amount += fee (integer base-units math), shipping_fee/est_days snapshotted, payable_* reference conversion REBUILT at the new total, payment window clock starts, order → direct_pay_window. Buyer decline = existing /cancel; seller withdraw = existing /decline (both no-fault + restock, nobody has paid). Plain /accept on a quote order is rejected (409 QUOTE_REQUIRED) so the fee step cannot be bypassed. AML monitor re-runs after the total change (fail-soft). Escrow-rail quote remains unavailable (create still 409 SHIP_REGION_NOT_COVERED; requires the pay-after-accept money path — separate revision). No new order state or edge (rides pending_accept + the existing pending_accept→direct_pay_window system edge); registered by hand.', migration: 'Agents on direct_p2p: create may return status pending_accept with shipping_quote_required=true even for auto-accept products — wait for the seller quote, then read shipping_quote_fee and call confirm-quote to consent to the NEW total (total_amount changes on confirmation; the D1/D2 + mark_paid gates are unchanged and payment info stays hidden until direct_pay_window). Do not expect /accept to work on quote orders (409 QUOTE_REQUIRED).' },
+    { contract_version: 19, date: '2026-07-05', surface: 'entity', kind: 'added', summary: '§① order lifecycle gains a disputed→confirmed edge, allowed actor \'buyer\' ONLY: the buyer may WITHDRAW a fulfilment dispute and confirm receipt (撤诉并确认收货) — e.g. a "package never arrived" parcel later turns up at a pickup point. Closes the gap where a delivered-origin dispute could only end via arbitration or mutual-cancel: both consensual closures now exist (seller-side = mutual-cancel full refund; buyer-side = this edge). New order action POST /api/orders/:id/action {action:"dispute_withdraw_confirm"} — RESTRICTED (route + DTO fail-closed, same pattern as pq_withdraw) to disputes whose most recent entry into disputed was from delivered (fulfilment disputes; payment_query-originated disputes keep their own pq_withdraw negotiation return), AND caller = buyer = dispute initiator, AND the dispute is still open/in_review (post-ruling → DISPUTE_ALREADY_RULED). Executed ATOMICALLY in one db.transaction: active dispute → dismissed (NO fault, NO reputation change, NO arbitration fee for either side) + disputed→confirmed→completed + settleOrder — the identical settlement chain to a normal confirm (escrow: funds release to seller; direct_p2p: platform fee accrues). On direct_p2p this is a RISK action: both D1/D2 disclosure acks + a live-Passkey gate token (purpose=direct_pay_order_action, purpose_data {order_id, action:"dispute_withdraw_confirm"}) are required — agents cannot perform it. The order DTO exposes can_confirm_receipt_close_dispute to signal when it is offered.', migration: 'Agents/integrators: a disputed order can now reach confirmed/completed via buyer dispute-withdrawal — treat disputed as non-terminal toward completion as well as cancellation. Offer the action only when can_confirm_receipt_close_dispute is true; server returns NOT_FULFILMENT_DISPUTE / NOT_DISPUTE_INITIATOR / DISPUTE_ALREADY_RULED otherwise. On direct_p2p a Passkey gate token is required (HUMAN_PRESENCE_REQUIRED without it). No existing state/edge/actor changed.' },
+    { contract_version: 20, date: '2026-07-05', surface: 'capability', kind: 'added', summary: 'Cross-border trade-terms skeleton (S0 of the cross-border series): (a) products gain OPTIONAL customs/logistics evidence fields on POST /api/products + PUT update — package_size, origin_country, country_of_origin, customs_description, hs_code (validated lightly: region codes uppercased ≤8 chars, hs_code 4-12 digits/dots, 400 INVALID_HS_CODE otherwise; display/evidence only, ZERO pricing logic). (b) every NEW order freezes a trade_terms snapshot at create (both rails): shipping ruling (source template|quote_pending|quote|none + region/fee/est_days; the quote slot is updated once when the buyer confirms a manual quote), fulfilment promises (handling_hours/estimated_days/return_days/return_condition/warranty_days), the customs/logistics fields above, seller declarations (free-text ship_regions + reserved structured slots), and the effective accept_mode — seller setting changes NEVER affect in-flight orders, and disputes get a written record of the terms at purchase time. GET /api/orders/:id returns it parsed as trade_terms (null for pre-S0 orders / bad JSON — consumers MUST tolerate null); the raw column is never serialized (list endpoint strips it). Reserved (columns exist, NOT accepted by any API yet — deliberately no fake switches): sale_regions / tax_lines / import_duty_terms — these activate in later revisions together with their enforcement gates (sellable-region gate; tax lines into totals with DDP/DDU declarations). Snapshot writes are fail-soft and are NOT part of any money path. Not part of the §②/§① fingerprint; registered by hand.', migration: 'Integrators: treat order.trade_terms as optional (null on older orders). Sellers MAY declare customs evidence fields on listings — they surface in order snapshots and buyer-facing detail; they do not change pricing, shipping fees or deadlines. Do NOT send sale_regions/tax_lines/import_duty_terms yet — they are rejected/ignored until the gates ship.' },
+    { contract_version: 21, date: '2026-07-05', surface: 'capability', kind: 'added', summary: 'Sellable regions (S1 of the cross-border series): sellers may now declare WHERE they sell, independent of shipping fees. POST /api/seller/shipping-template accepts store_sale_regions and/or {product_id, sale_regions} — rule shape {mode:"all"|"list", include?:[..], exclude?:[..]} (uppercase region codes; null clears; product overrides store; strict validation, 400 BAD_SALE_REGIONS). GET /api/seller/shipping-settings returns the parsed store rule. ENFORCEMENT: POST /api/orders now runs a sellable-region gate BEFORE the shipping gate, on BOTH rails, with the destination-capability taxonomy: 409 REGION_NOT_FOR_SALE (merchant will — a hard reject, deliberately NOT eligible for the quote-on-accept path; not selling is not a pricing problem), 409 PRODUCT_RESTRICTED (platform compliance overlay via the admin protocol param trade.platform_region_blocklist — merchants cannot widen it), 400 SHIP_REGION_REQUIRED (a rule exists but the buyer sent no ship_to_region — fail-closed). Products/stores without a rule behave exactly as before. The order trade_terms snapshot (v20) now carries the effective rule in declarations.sale_regions_rule. The legacy free-text products.ship_regions remains display-only and does NOT feed this gate. Not part of the §②/§① fingerprint; registered by hand.', migration: 'Agents placing orders: be ready for 409 REGION_NOT_FOR_SALE / PRODUCT_RESTRICTED and 400 SHIP_REGION_REQUIRED on POST /api/orders even for products without shipping templates. There is no quote fallback for REGION_NOT_FOR_SALE — pick a different destination or product. Sellers: declare rules via POST /api/seller/shipping-template; buyer-facing pre-checkout display of sellable regions ships in a later revision (S5).' },
+    { contract_version: 22, date: '2026-07-06', surface: 'capability', kind: 'added', summary: 'Free-shipping threshold as a MARKETING rule (S2 of the cross-border series; deliberately NOT a shipping-template field — templates stay pure cost/coverage structure, and under the future logistics-provider model the waiver is necessarily a merchant subsidy, so the rule lives where it will not need to move). Sellers set per-product products.free_shipping_threshold ?? store users.store_free_shipping_threshold (product overrides store) via POST /api/seller/shipping-template ({store_free_shipping_threshold} | {product_id, free_shipping_threshold}; positive finite, 400 BAD_FREE_SHIPPING_THRESHOLD; null clears). At order create, on BOTH rails, when the post-coupon goods subtotal (excluding insurance/donation) reaches the effective threshold AND the template fee for the destination is positive, the shipping fee is waived to 0 — comparison in integer base units, boundary >=. The manual quote-on-accept path is exempt (a human-priced quote is authoritative). The order trade_terms snapshot gains shipping.free_threshold_applied so disputes can distinguish waived-by-promotion from no-fee-configured. GET /api/seller/shipping-settings returns store_free_shipping_threshold. Additive; not part of the §②/§① fingerprint; registered by hand.', migration: 'Integrators: create totals may carry 0 shipping fee for covered regions when the goods subtotal reaches the seller\'s marketing threshold; read trade_terms.shipping.free_threshold_applied to distinguish. Shipping template entries are UNCHANGED (no promo fields).' },
+    { contract_version: 23, date: '2026-07-06', surface: 'capability', kind: 'added', summary: 'Cross-border tax & import-responsibility DECLARATION + DISCLOSURE layer (S3). Sellers declare, the platform does NOT compute/collect/remit tax (seller-of-record posture; see docs/COMPLIANCE-CROSS-BORDER-TAX.INTERNAL.md — non-custodial does NOT by itself exempt the platform from deemed-supplier/marketplace-facilitator status, so cross-border into high-enforcement regimes is counsel-gated via the S1 trade.platform_region_blocklist, not opened here). Two seller-declared fields, per-product ?? store, set via POST /api/seller/shipping-template: (1) import_duty_terms enum {ddu|ddp|null} — who bears destination import duty/tax (DDU = buyer pays on arrival; DDP = seller included it); 400 BAD_IMPORT_DUTY_TERMS. (2) tax_lines — an array of {region (uppercase code or *), label, rate_pct?, note?, kind:"included"} declaring taxes ALREADY INCLUDED in the price (e.g. SG GST 9%); kind is restricted to "included" and kind:"added" (tax added into the order total) is explicitly REJECTED — the money-path fold is a deliberately deferred future revision, the platform does not collect tax; 400 BAD_TAX_LINES. GET /api/products/:id/shipping-options now also returns import_duty_terms and tax_included_lines for pre-purchase buyer disclosure — tax_included_lines is FILTERED by an optional ?ship_to_region query param (destination match + wildcard \'*\' lines; no param = only \'*\' universal lines), so buyers are never shown taxes that do not apply to their destination; import_duty_terms is a single per-order flag (not region-scoped); GET /api/seller/shipping-settings returns store_import_duty_terms + store_tax_lines. The order trade_terms snapshot declarations.{import_duty_terms,tax_lines} slots (reserved in S0/contract v20) now fill from these columns. No order state/edge/money change; totals are unaffected (included-tax and DDP/DDU never alter total_amount). Additive; not part of the §②/§① fingerprint; registered by hand.', migration: 'Agents/integrators: read order.trade_terms.declarations.{import_duty_terms,tax_lines} and GET shipping-options?ship_to_region=XX {import_duty_terms,tax_included_lines} for a listing/order\'s declared tax posture (pass ship_to_region to get destination-applicable included-tax lines; omitting it returns only \'*\' universal lines). These are seller declarations only — the platform neither computes nor collects tax, and order totals are NOT changed by them (DDU import charges are paid by the buyer to the carrier at the border; DDP and included-tax are already inside the seller\'s price). Do NOT send tax_lines with kind:"added" (rejected).' },
 ];
 export function buildChangeFeed() {
     return {

package/dist/pwa/direct-pay-guards.js

@@ -0,0 +1,20 @@
+/**
+ * 直付 / 直接收款 RISK 门:
+ *   ① 无 Passkey credential → 硬拒(agent 路径:agent 不可能持有 Passkey assertion → 永远过不了)。
+ *   ② 需一次性真人 WebAuthn gate token(purpose-bound, 60s)。
+ * 两步都过才返回 ok。无自助批准路径。
+ */
+export function requireDirectPayHumanPasskey(deps, args) {
+    const { db, consumeGateToken } = deps;
+    const { userId, webauthnToken, purpose, validate } = args;
+    // ① agent 硬拒:没有 Passkey 凭证的身份(agent)绝不能发起/批准直付
+    const hasPk = db.prepare('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?').get(userId).n > 0;
+    if (!hasPk) {
+        return { ok: false, error_code: 'PASSKEY_REQUIRED_FOR_DIRECT_PAY', reason: '直付/直接收款是 RISK 操作:需绑定 Passkey 并真人二次确认,agent 不可代操作' };
+    }
+    // ② 一次性 purpose-bound 真人 WebAuthn gate token
+    const gate = consumeGateToken(userId, webauthnToken, purpose, validate ?? (() => true));
+    if (!gate.ok)
+        return { ok: false, error_code: 'HUMAN_PRESENCE_REQUIRED', reason: gate.reason || '需真实人工 WebAuthn 验证' };
+    return { ok: true };
+}

package/dist/pwa/direct-pay-order-redaction.js

@@ -0,0 +1,42 @@
+import { requireBothDisclosuresAcked } from '../direct-pay-disclosures.js';
+/** 买家自视角:未 both-acked 的 direct_p2p 订单,删收款目标(instruction 原文 + 账号快照 qr_ref)。就地改 o。
+ *  手动接单(v16):pending_accept 阶段【状态门】无条件遮蔽 —— 卖家还没确认能发货,买家不该拿到任何收款信息
+ *  (哪怕已 ack 披露;时序门=非托管唯一付款风控,接单后才起表付款窗)。 */
+export function redactUnackedDirectPayTarget(db, o, userId) {
+    if (o.payment_rail !== 'direct_p2p' || o.buyer_id !== userId)
+        return;
+    if (o.status !== 'pending_accept' && requireBothDisclosuresAcked(db, o.id).ok)
+        return;
+    delete o.direct_pay_instruction_snapshot;
+    if (o.direct_pay_account_snapshot != null) {
+        try {
+            const s = JSON.parse(o.direct_pay_account_snapshot);
+            delete s.qr_ref;
+            o.direct_pay_account_snapshot = JSON.stringify(s);
+        }
+        catch {
+            delete o.direct_pay_account_snapshot;
+        }
+    }
+}
+/** 无条件删除收款目标(instruction 快照 + 整个账号快照)。用于非买家第三方 reader,他们绝不该看到收款目标。就地改 o。 */
+export function stripDirectPayPaymentTarget(o) {
+    delete o.direct_pay_instruction_snapshot;
+    delete o.direct_pay_account_snapshot;
+}
+/**
+ * 【唯一入口】按查看者投影收款目标(#218 审计发现 6):三类查看者一次分派,route 不再手工按序组合两个原语 ——
+ * 曾经的组合错法每种都真实发生过:列表只调 redact(→ logistics 第三方拿到收款目标)、详情只调 redact(→ 仲裁员拿到)。
+ *   - 卖家(o.seller_id===viewerId):收款方,instruction 是他自填的 → 不动。
+ *   - 买家:ack 门(redactUnackedDirectPayTarget —— 未 both-acked 删 instruction+剥 qr_ref,留非敏感元数据)。
+ *   - 其他一切查看者(logistics/仲裁员/admin/任何第三方):无条件剥离(stripDirectPayPaymentTarget)。
+ * escrow 单不含收款目标语义,原语各自 no-op/删空,安全。所有返回 orders 整行的 reader 必须调本函数
+ * (reader-guard 的 GATE 认的就是本函数名);两个原语仍导出,仅作本函数的构件,route 层不应直接使用。
+ */
+export function projectDirectPayTargetForViewer(db, o, viewerId) {
+    if (o.seller_id === viewerId)
+        return;
+    if (o.buyer_id === viewerId)
+        return redactUnackedDirectPayTarget(db, o, viewerId);
+    stripDirectPayPaymentTarget(o);
+}

package/dist/pwa/endpoint-actions.js

@@ -31,6 +31,9 @@ export const WRITE_RULES = [
     { method: 'POST', re: /^\/api\/skill-market\/[^/]+\/purchase/, action: 'purchase' },
     { method: 'POST', re: /^\/api\/secondhand\/[^/]+\/order/, action: 'buy_secondhand' },
     { method: 'POST', re: /^\/api\/group-buys\/[^/]+\/join/, action: 'group_buy_join' },
+    // Direct Pay (Rail 1) = RISK scope:为【未来】/api/direct-pay/* 写面【保留】'direct_pay' 分类(该面尚无路由)。
+    //   ⚠️ SCAFFOLD:Passkey/两次披露门当前是 helper,【尚未】接到任何 handler;真实 enforcement 随 create-route/UI/ack 端点在后续 PR 落地。
+    { method: 'WRITE', re: /^\/api\/direct-pay\//, action: 'direct_pay' },
     // Codex #98 P1:review claim 锁 5 WAZ stake(扣 balance + escrowed)—— 资金写,绝不能落 SAFE,纳入 default-deny 问责门。
     //   只命中 .../:type/:id/claim;其余 reviews 写无规则 → 落通用 'write'(仍 default-deny),GET reviews 由 endpointToAction(GET) 返回 null。
     { method: 'POST', re: /^\/api\/reviews\/[^/]+\/[^/]+\/claim$/, action: 'review_claim' },

package/dist/pwa/human-presence.js

@@ -37,7 +37,8 @@ export function createHumanPresence(db, getProtocolParam) {
     // ─── Agent 治理铁律:人工铁律节点 ───
     // 关键节点(verifier 投票 / arbitrator 仲裁 / agent_revoke / delete_passkey / identity_claim)必须真实
     // 人工参与,agent 代操作被拦截。实现:要求 webauthn_gate_token(一次性 · 60s)+ 协议参数开关。
-    // is_system fixture 旁路只对 vote/arbitrate 生效(有白名单表);其余无豁免。
+    // is_system fixture 旁路【只对 vote 生效】。PR-C:arbitrate 旁路已移除 —— HTTP 人类仲裁路由所有真人仲裁员都必须
+    //   现场 Passkey(consumeGateToken)。sys_protocol 自动裁决走 engine arbitrateDispute(role=system,不经此函数),不受影响。
     function requireHumanPresence(userId, purpose, token, paramKey, validate = () => true) {
         const enabled = Number(getProtocolParam(paramKey, 1)) === 1;
         if (!enabled)
@@ -47,11 +48,6 @@ export function createHumanPresence(db, getProtocolParam) {
             if (wl?.is_system === 1)
                 return { ok: true };
         }
-        else if (purpose === 'arbitrate') {
-            const wl = db.prepare('SELECT is_system FROM arbitrator_whitelist WHERE user_id = ?').get(userId);
-            if (wl?.is_system === 1)
-                return { ok: true };
-        }
         const result = consumeGateToken(userId, token, purpose, validate);
         if (!result.ok) {
             return { ok: false, error_code: 'HUMAN_PRESENCE_REQUIRED', reason: result.reason || '此操作需真实人工 WebAuthn 验证', required_when_enabled: true };

package/dist/pwa/public/app-account.js

@@ -117,7 +117,7 @@ async function renderMyAdvanced(app) {
 }
 
 async function renderProfile(app) {
-  app.innerHTML = shell(loading$(), 'me')
+  if (state.apiKey && !state.user) { const me = await GET('/me'); if (!me.error) state.user = me } app.innerHTML = shell(loading$(), 'me')   // 自愈(修"切角色/改密后假登出"):switchRole/addRole/set-password 置空 state.user 后绕过 render() 路由直调本函数,shell 曾画成未登录(header 变登录钮/底栏错乱,不自愈) → 先权威重取再画
   const [data, blocklist] = await Promise.all([
     GET('/profile'),
     GET('/blocklist/me').catch(() => ({ blocked: [] })),
@@ -131,12 +131,12 @@ async function renderProfile(app) {
   const allRoles  = [...SELF_SERVE_ROLES, ...APPLY_ROLES]
   const roleLabels = { buyer: t('买家'), seller: t('卖家'), logistics: t('物流'), arbitrator: t('仲裁员'), verifier: t('审核员'), admin: t('管理员') }
   const roleIcons  = { buyer: '🛍️', seller: '🏪', logistics: '🚚', arbitrator: '⚖️', verifier: '🔍', admin: '🛡' }
-  const addable = allRoles.filter(r => !roles.includes(r))
+  if (!state.canArbitrate) { try { const _as = await GET('/arbitrator/status'); state.canArbitrate = !!(_as && _as.can_arbitrate) } catch {} } const addable = allRoles.filter(r => !roles.includes(r) && !(r === 'arbitrator' && state.canArbitrate))   // #249-P3:仲裁资格=白名单非角色,roles 判不出 → 现场查;已持资格不再被邀请"申请仲裁员"
   // 受信角色：admin / verifier / logistics / arbitrator — 隐藏交易/社交相关 UI
   const TRUSTED_ROLES = ['admin', 'verifier', 'logistics', 'arbitrator']
   const isTrustedRole = TRUSTED_ROLES.includes(data.role) || roles.some(r => ['admin','verifier'].includes(r))
-  // 受信角色显示的"已有角色" chip 只展示受信角色（隐藏 buyer/seller，即使账户有遗留多角色）
-  const visibleRoles = isTrustedRole ? roles.filter(r => TRUSTED_ROLES.includes(r)) : roles
+  const identityLocked = ['admin', 'verifier'].includes(data.role) || roles.some(r => ['admin', 'verifier'].includes(r))   // 角色 chip 过滤:身份锁只看 admin/verifier(与服务端 switch-role 守卫同谓词)。此前 arbitrator/logistics active 也触发过滤 → legacy 仲裁员角色下 buyer/seller chip 被藏切不回买家(梦想者1号案);服务端本就允许该切换,前后端对齐
+  const visibleRoles = identityLocked ? roles.filter(r => TRUSTED_ROLES.includes(r)) : roles
 
   app.innerHTML = shell(`
     ${mySubTabsHTML('settings')}
@@ -204,7 +204,7 @@ async function renderProfile(app) {
               ${roleIcons[r]} ${roleLabels[r]}
               ${r === data.role ? `<span style="font-size:11px;color:#3b82f6">${t('● 激活')}</span>` : ''}
             </button>
-          `).join('')}
+          `).join('')}${state.canArbitrate ? `<span title="${t('仲裁资格是白名单能力,叠加在你的买卖身份上,不是可切换角色')}" style="display:inline-flex;align-items:center;gap:6px;padding:8px 14px;border-radius:10px;font-size:14px;border:2px dashed #c4b5fd;background:#f5f3ff;color:#6b21a8">⚖️ ${t('仲裁员资格(白名单)')}</span>` : ''}
         </div>
 
         ${roles.some(r => ['admin','verifier'].includes(r)) ? `
@@ -227,8 +227,8 @@ async function renderProfile(app) {
             <div style="font-size:13px;color:#6b7280;margin:12px 0 6px">${t('需通过申请获得')}</div>
             <div style="display:flex;flex-wrap:wrap;gap:8px">
               ${addable.filter(r => APPLY_ROLES.includes(r)).map(r => {
-                if (r === 'verifier') {
-                  return `<button onclick="navigate('#apply-verifier')" style="
+                if (r === 'verifier' || r === 'arbitrator') {   // 走查批次3:仲裁员早已不是"角色"(资格=白名单+个案COI,#220),灰死"联系管理员"chip 是旧模型残留 → 与审核员一致跳真实申请流程(不切角色,保留买卖身份)
+                  return `<button onclick="navigate('${r === 'verifier' ? '#apply-verifier' : '#apply-arbitrator'}')" style="
                     display:flex;align-items:center;gap:6px;padding:8px 14px;border-radius:10px;font-size:14px;cursor:pointer;
                     background:#eef2ff;border:2px solid #6366f1;color:#4338ca
                   ">${roleIcons[r]} 📥 ${t('申请')} ${roleLabels[r]}</button>`
@@ -438,7 +438,7 @@ async function renderProfile(app) {
             ${t('提现等敏感操作可要求设备指纹 / Face ID 二次确认。私钥不离开你的手机，手机丢失也不会泄露。')}
           </div>
           <div id="passkey-list" style="font-size:12px;color:#6b7280">${t('加载中…')}</div>
-          <a onclick="navigate('#agents')" style="display:block;margin-top:12px;font-size:12px;color:#4f46e5;cursor:pointer">🔌 ${t('已连接的 Agent')} →</a>
+          <a onclick="navigate('#agents')" style="display:block;margin-top:12px;font-size:12px;color:#4f46e5;cursor:pointer">🔌 ${t('已连接的 Agent')} →</a><a onclick="navigate('#agent-approvals')" style="display:block;margin-top:8px;font-size:12px;color:#4f46e5;cursor:pointer">🔔 ${t('Agent 授权请求')}<span id="aa-pending-badge"></span> →</a>
         </div>
       </div>
     </div>
@@ -552,7 +552,7 @@ async function renderProfile(app) {
   })()
 
   // 加载 Passkey 列表
-  refreshPasskeyList()
+  refreshPasskeyList(); if (window.hydrateAgentApprovalsBadge) hydrateAgentApprovalsBadge()
 }
 
 async function refreshPasskeyList() {

package/dist/pwa/public/app-admin-disputes.js

@@ -0,0 +1,55 @@
+// admin 争议查看/管理 —— 可【区分】(状态 / 直付-托管 / 进度 / 是否已指派 / 如何结案 / 紧急度)+ 可【管理】(状态过滤 + 钻取查看)。
+//   admin 只读监督(后端 disputes-read 允许 admin 查详情);裁定/驳回等【动作】仍须 active 白名单仲裁员(COI+指派)。中文 t(),英文 i18n.js。
+window.renderAdminDisputes = async function (app, opts = {}) {
+  if (!state.user) { renderLogin(); return }
+  if (!isAdmin()) { app.innerHTML = shell(`<div class="alert alert-info">${t('仅限管理员')}</div>`, 'admin'); return }
+  app.innerHTML = shell(loading$(), 'admin')
+  const status = opts.status || ''
+  const data = await GET('/admin/disputes' + (status ? `?status=${encodeURIComponent(status)}` : ''))
+  if (data.error) { app.innerHTML = shell(alert$('error', data.error), 'admin'); return }
+  const c = data.counts || {}
+  const STATUS_META = { open: ['#fef3c7', '#92400e', t('待响应')], in_review: ['#fde68a', '#b45309', t('仲裁中')], resolved: ['#dcfce7', '#166534', t('已裁定')], dismissed: ['#e5e7eb', '#374151', t('已驳回')] }
+  const tabs = [['', t('全部'), data.total || 0], ['open', t('待响应'), c.open || 0], ['in_review', t('仲裁中'), c.in_review || 0], ['resolved', t('已裁定'), c.resolved || 0], ['dismissed', t('已驳回'), c.dismissed || 0]]
+  const tabHtml = tabs.map(([val, label, n]) => `<button class="btn btn-sm" style="width:auto;font-size:12px;background:${status === val ? '#4f46e5' : '#fff'};color:${status === val ? '#fff' : '#374151'};border:1px solid ${status === val ? '#4f46e5' : '#e5e7eb'}" onclick="renderAdminDisputes(document.getElementById('app'),{status:'${val}'})">${label} ${n}</button>`).join('')
+  const railBadge = (rail) => rail === 'direct_p2p'
+    ? `<span style="font-size:10px;background:#eff6ff;color:#1e40af;padding:1px 7px;border-radius:99px">${t('直付')}</span>`
+    : `<span style="font-size:10px;background:#f0fdf4;color:#166534;padding:1px 7px;border-radius:99px">${t('托管')}</span>`
+  const urgencyChip = (d) => {
+    if (d.status !== 'open' && d.status !== 'in_review') return ''
+    const dl = d.status === 'open' ? d.respond_deadline : d.arbitrate_deadline
+    if (!dl) return ''
+    const overdue = new Date(dl) < new Date()
+    return `<span style="font-size:10px;background:${overdue ? '#fee2e2' : '#fff7ed'};color:${overdue ? '#991b1b' : '#9a3412'};padding:1px 7px;border-radius:99px">${overdue ? '⏰ ' + t('已超时') : '⏳ ' + fmtTime(dl)}</span>`
+  }
+  const assignChip = (d) => {
+    let n = 0; try { n = (JSON.parse(d.assigned_arbitrators || '[]') || []).length } catch {}
+    return `<span style="font-size:10px;background:${n ? '#ede9fe' : '#f3f4f6'};color:${n ? '#5b21b6' : '#9ca3af'};padding:1px 7px;border-radius:99px">${n ? '⚖ ' + t('已指派') : t('未指派')}</span>`
+  }
+  const verdictChip = (d) => (d.status === 'resolved' || d.status === 'dismissed') && d.ruling_type
+    ? `<span style="font-size:10px;background:#f5f3ff;color:#6d28d9;padding:1px 7px;border-radius:99px">${(window.dpRulingLabel && window.dpRulingLabel(d.ruling_type)) || t(d.ruling_type)}</span>` : ''
+  const list = (data.disputes || []).map(d => {
+    const [bg, fg, lbl] = STATUS_META[d.status] || ['#e5e7eb', '#374151', d.status]
+    return `<div class="card" style="margin-bottom:10px;font-size:13px;cursor:pointer" onclick="navigate('#dispute/${escHtml(d.id)}')">
+      <div style="display:flex;justify-content:space-between;align-items:flex-start;gap:8px">
+        <div style="flex:1;min-width:0">
+          <div style="font-weight:600;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${escHtml(d.product_title || '—')}</div>
+          <div style="font-size:12px;color:#6b7280;margin-top:2px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${escHtml((d.reason || '').slice(0, 60))}</div>
+          <div style="font-size:11px;color:#6b7280;margin-top:6px">${t('原告')}: ${escHtml(d.initiator_name || '—')} → ${t('被告')}: ${escHtml(d.defendant_name || '—')}</div>
+          <div style="display:flex;gap:5px;flex-wrap:wrap;margin-top:6px">${railBadge(d.payment_rail)}${assignChip(d)}${urgencyChip(d)}${verdictChip(d)}</div>
+          <div style="font-size:11px;color:#9ca3af;margin-top:6px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${escHtml(d.id)} · ${fmtTime(d.created_at)}</div>
+        </div>
+        <div style="display:flex;flex-direction:column;gap:6px;align-items:flex-end;flex-shrink:0">
+          <span style="background:${bg};color:${fg};padding:2px 8px;border-radius:8px;font-size:11px;white-space:nowrap">${lbl}</span>
+          ${d.total_amount ? `<div style="font-size:12px;color:#374151;white-space:nowrap">${d.total_amount} WAZ</div>` : ''}
+        </div>
+      </div>
+    </div>`
+  }).join('') || `<div class="empty"><div class="empty-icon">⚖️</div><div class="empty-text">${t('暂无争议')}</div></div>`
+  app.innerHTML = shell(`
+    <h1 class="page-title">⚖️ ${t('争议查看')}</h1>
+    <div style="margin-bottom:12px"><button class="btn btn-outline btn-sm" style="width:auto" onclick="navigate('#admin')">${t('返回概览')}</button></div>
+    <div style="display:flex;gap:6px;flex-wrap:wrap;margin-bottom:12px">${tabHtml}</div>
+    <div style="font-size:11px;color:#9ca3af;margin-bottom:8px">${t('点卡片查看争议详情(只读监督;裁定须仲裁员)')}</div>
+    ${list}
+  `, 'admin')
+}

package/dist/pwa/public/app-agent-appeal.js

@@ -0,0 +1,90 @@
+// 被封用户申诉页 + admin strike 审批页(Tina 案补齐 UI)。UI ONLY —— 申诉/裁决边界全在后端;
+//   被封状态下只调两个封禁豁免端点(GET /api/me/agents、POST .../strikes/:id/appeal)。
+;(function () {
+  const SEV = () => ({ warning: t('警告'), suspend_7d: t('暂停 7 天'), permanent: t('永久封禁') })
+  const APL = () => ({ none: t('未申诉'), pending: t('申诉审核中'), approved: t('申诉通过(已解封)'), denied: t('申诉被驳回') })
+
+  // ── 被封用户:极简申诉页(登录检测到 AGENT_BLOCKED 时进入;key 已在 state.apiKey)──
+  window.renderAgentBlockedAppeal = async (blockMsg) => {
+    const app = document.getElementById('app')
+    app.innerHTML = `<div style="max-width:560px;margin:40px auto;padding:0 16px">
+      <h1 style="font-size:18px;font-weight:700;margin-bottom:8px">🚫 ${t('账号处于暂停期')}</h1>
+      <div class="alert alert-error" style="margin-bottom:12px">${escHtml(blockMsg || '')}</div>
+      <div id="appeal-box">${loading$()}</div></div>`
+    const r = await GET('/me/agents').catch(() => null)
+    const box = document.getElementById('appeal-box')
+    if (!r || !Array.isArray(r.items)) { box.innerHTML = `<div class="alert alert-error">${t('加载失败,请重试(确认 key 完整)')}</div>`; return }
+    const strikes = r.items.flatMap(a => (a.recent_strikes || []))
+    const active = strikes.find(s => ['suspend_7d', 'permanent'].includes(s.severity) && s.appeal_status !== 'approved')
+    if (!active) { box.innerHTML = `<div class="alert alert-info">${t('未发现生效中的封禁,请重新登录试试')}</div>`; return }
+    const S = SEV(); const A = APL()
+    box.innerHTML = `
+      <div class="card" style="font-size:13px">
+        <div><strong>${S[active.severity] || active.severity}</strong> · ${escHtml(active.reason_code)}${active.reason_detail ? `(${escHtml(active.reason_detail)})` : ''}</div>
+        <div style="color:#6b7280;margin-top:4px">${t('签发')}:${fmtTime(active.issued_at)}${active.expires_at ? ` · ${t('到期自动解除')}:${fmtTime(active.expires_at)}` : ''}</div>
+        <div style="margin-top:4px">${t('申诉状态')}:<strong>${A[active.appeal_status] || active.appeal_status}</strong></div>
+      </div>
+      ${active.appeal_status === 'none' ? `
+      <textarea class="form-control" id="appeal-reason" rows="3" maxlength="500" placeholder="${t('申诉理由(≥10 字;说明误触发原因,如页面挂机轮询/误操作)')}" style="margin:10px 0;font-size:13px"></textarea>
+      <button class="btn btn-primary" style="width:100%" onclick="agentAppealSubmit(${active.id})">${t('提交申诉(等待管理员审核)')}</button>`
+      : active.appeal_status === 'pending' ? `<div class="alert alert-info" style="margin-top:10px">${t('申诉已提交,等待管理员审核;审核通过后重新登录即可。')}</div>`
+      : active.appeal_status === 'denied' ? `<div class="alert alert-error" style="margin-top:10px">${t('申诉被驳回;封禁将按期自动解除。')}</div>` : ''}
+      <button class="btn btn-outline btn-sm" style="width:100%;margin-top:10px" onclick="state.apiKey=null;location.reload()">${t('退出(换个账号登录)')}</button>`
+  }
+  window.agentAppealSubmit = async (strikeId) => {
+    const reason = (document.getElementById('appeal-reason')?.value || '').trim()
+    if (reason.length < 10) return void toast$(t('申诉理由 ≥10 字'), 'error')
+    const r = await POST(`/me/agents/strikes/${strikeId}/appeal`, { reason })
+    if (r.error) return void toast$(r.error, 'error')
+    toast$(t('申诉已提交'), 'success'); window.renderAgentBlockedAppeal('')
+  }
+
+  // ── admin:#admin/agent-strikes 待审队列 + 裁决 + 主动 issue ──
+  window.renderAdminAgentStrikes = function (app) {
+    if (!state.user) { renderLogin(); return }
+    if (typeof isAdmin === 'function' && !isAdmin()) { app.innerHTML = shell(`<div class="alert alert-info">${t('仅限管理员')}</div>`, 'admin'); return }
+    if ((state.user.admin_type || 'root') !== 'root') { app.innerHTML = shell(`<div class="alert alert-info">${t('仅限根管理员')}</div>`, 'admin'); return }
+    app.innerHTML = shell(`
+      <h1 class="page-title">🚦 ${t('Agent 封禁与申诉')}</h1>
+      <div style="font-size:12px;color:#6b7280;margin-bottom:10px">${t('申诉批准=立即解封(60 秒缓存内生效);驳回=按期自动解除。真人(绑 Passkey)已豁免速率封禁,此页主要处理 agent 与历史误封。')}</div>
+      <div id="strike-adm-box">${loading$()}</div>
+      <h2 style="font-size:14px;font-weight:700;margin:16px 0 8px">${t('主动签发 strike(慎用)')}</h2>
+      <div style="display:flex;gap:6px;flex-wrap:wrap;margin-bottom:8px">
+        <input class="form-control" id="stk-key" placeholder="api_key" style="flex:2;min-width:160px;font-size:12px">
+        <input class="form-control" id="stk-reason" placeholder="${t('reason_code(如 spam / fake_shipment)')}" style="flex:1;min-width:120px;font-size:12px">
+        <select class="form-control" id="stk-sev" style="width:auto;font-size:12px"><option value="warning">warning</option><option value="suspend_7d">suspend_7d</option><option value="permanent">permanent</option></select>
+        <button class="btn btn-outline btn-sm" style="width:auto;font-size:11px" onclick="adminStrikeIssue()">${t('签发')}</button>
+      </div>`, 'admin')
+    window.adminStrikesHydrate()
+  }
+  window.adminStrikesHydrate = async () => {
+    const box = document.getElementById('strike-adm-box'); if (!box) return
+    const r = await GET('/admin/agent-strikes/pending').catch(() => null)
+    const items = (r && r.items) || []
+    const S = SEV()
+    box.innerHTML = items.length === 0 ? `<div class="alert alert-info">${t('暂无待审申诉')}</div>` : items.map(i => `
+      <div class="card" style="font-size:12px">
+        <div style="display:flex;justify-content:space-between;gap:8px;flex-wrap:wrap">
+          <div><strong>@${escHtml(i.handle || i.user_id)}</strong> · ${S[i.severity] || i.severity} · ${escHtml(i.reason_code)}</div>
+          <div style="color:#6b7280">${fmtTime(i.issued_at)}</div>
+        </div>
+        ${i.reason_detail ? `<div style="color:#6b7280;margin-top:4px">${t('签发详情')}:${escHtml(i.reason_detail)}</div>` : ''}
+        <div style="margin-top:6px;padding:8px;background:#f9fafb;border-radius:6px">💬 ${t('申诉理由')}:${escHtml(i.appeal_reason || '-')}</div>
+        <div style="display:flex;gap:8px;margin-top:8px">
+          <button class="btn btn-primary btn-sm" style="width:auto;font-size:11px" onclick="adminStrikeDecide(${i.id},'approved')">${t('批准(立即解封)')}</button>
+          <button class="btn btn-outline btn-sm" style="width:auto;font-size:11px;color:#dc2626;border-color:#fecaca" onclick="adminStrikeDecide(${i.id},'denied')">${t('驳回')}</button>
+        </div>
+      </div>`).join('')
+  }
+  window.adminStrikeDecide = async (id, decision) => {
+    const r = await POST(`/admin/agent-strikes/${id}/decide`, { decision })
+    if (r.error) return void toast$(r.error, 'error')
+    toast$(decision === 'approved' ? t('已批准,60 秒内解封') : t('已驳回'), 'success'); window.adminStrikesHydrate()
+  }
+  window.adminStrikeIssue = async () => {
+    if (typeof confirmModal === 'function' && !(await confirmModal(t('确认签发 strike?suspend_7d/permanent 将立即阻断该 key 的所有访问。'), t('签发'), { danger: true }))) return
+    const r = await POST('/admin/agent-strikes/issue', { api_key: (document.getElementById('stk-key')?.value || '').trim(), reason_code: (document.getElementById('stk-reason')?.value || '').trim(), severity: document.getElementById('stk-sev')?.value })
+    if (r.error) return void toast$(r.error, 'error')
+    toast$(t('已签发'), 'success')
+  }
+})()