@seasonkoh/webaz 0.1.24 → 0.1.26

package/dist/layer4-economics/L4-4-skill-market/skill-engine.js

@@ -16,6 +16,7 @@
  *   - 其他技能目前免费（增强曝光，间接提升成交）
  */
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 seam(纯读)
 import { toUnits, toDecimal } from '../../money.js';
 import { applyWalletDelta } from '../../ledger.js';
 // ─── Schema ───────────────────────────────────────────────────
@@ -135,7 +136,9 @@ export function publishSkill(db, input) {
   `).run(id, input.sellerId, input.name, input.description, input.category ?? 'general', input.skillType, config, input.pricePerUse ?? 0);
     return getSkillById(db, id);
 }
-export function listSkills(db, filter = {}) {
+// RFC-016 Phase 1:纯读 → 异步 seam(db 参数保留签名兼容;调用点均确认不在 db.transaction 内)。
+//   注:getSkillById(被同步写 publishSkill 内部调用)+ shouldAutoAccept(orders-create tx 内)留 Phase 3。
+export async function listSkills(_db, filter = {}) {
     const params = [];
     let sql = `
     SELECT s.*, u.name as seller_name,
@@ -161,7 +164,7 @@ export function listSkills(db, filter = {}) {
     }
     sql += ` ORDER BY s.total_uses DESC, s.rating DESC LIMIT ?`;
     params.push(filter.limit ?? 20);
-    return db.prepare(sql).all(...params);
+    return await dbAll(sql, params);
 }
 export function getSkillById(db, skillId) {
     return db.prepare(`
@@ -170,12 +173,12 @@ export function getSkillById(db, skillId) {
     FROM skills s JOIN users u ON s.seller_id = u.id WHERE s.id = ?
   `).get(skillId);
 }
-export function getMySkills(db, sellerId) {
-    return db.prepare(`
+export async function getMySkills(_db, sellerId) {
+    return await dbAll(`
     SELECT s.*,
       (SELECT COUNT(*) FROM skill_subscriptions ss WHERE ss.skill_id = s.id AND ss.active = 1) as subscriber_count
     FROM skills s WHERE s.seller_id = ? ORDER BY s.created_at DESC
-  `).all(sellerId);
+  `, [sellerId]);
 }
 // ─── 订阅 / 取消订阅 ──────────────────────────────────────────
 export function subscribeSkill(db, userId, skillId, config = {}) {
@@ -195,8 +198,8 @@ export function subscribeSkill(db, userId, skillId, config = {}) {
 export function unsubscribeSkill(db, userId, skillId) {
     db.prepare('UPDATE skill_subscriptions SET active = 0 WHERE skill_id = ? AND user_id = ?').run(skillId, userId);
 }
-export function getMySubscriptions(db, userId) {
-    return db.prepare(`
+export async function getMySubscriptions(_db, userId) {
+    return await dbAll(`
     SELECT s.*, u.name as seller_name, 1 as subscribed,
       (SELECT COUNT(*) FROM skill_subscriptions ss WHERE ss.skill_id = s.id AND ss.active = 1) as subscriber_count
     FROM skill_subscriptions sub
@@ -204,7 +207,7 @@ export function getMySubscriptions(db, userId) {
     JOIN users u ON s.seller_id = u.id
     WHERE sub.user_id = ? AND sub.active = 1
     ORDER BY sub.created_at DESC
-  `).all(userId);
+  `, [userId]);
 }
 // ─── 使用记录 + 佣金 ──────────────────────────────────────────
 /**

package/dist/layer4-economics/L4-4-skill-market/skill-listing-engine.js

@@ -18,6 +18,7 @@
  *   绝不进入 PV 二元匹配 / 推土机三级佣金 / fund_base —— 保持双引擎解耦、规避 PV 合规问题。
  */
 import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { dbOne, dbAll } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 seam(纯读)
 import { toUnits, toDecimal } from '../../money.js';
 import { applyWalletDelta } from '../../ledger.js';
 export const SKILL_KINDS = ['template', 'prompt', 'guide', 'checklist'];
@@ -170,7 +171,9 @@ function getListingRaw(db, id) {
     return db.prepare('SELECT * FROM skill_listings WHERE id = ?').get(id);
 }
 /** 公开列表：仅 approved + active 的技能，不含 content */
-export function listMarket(db, filter = {}) {
+// RFC-016 Phase 1:纯读 → 异步 seam(db 参数保留签名兼容;调用点 skill-market.ts 均 inTx=false)。
+//   注:hasUnlock(被同步写 purchaseListing/readContent 复用)留 Phase 3,故 getMarketDetail 的 owned 检查内联为 dbOne。
+export async function listMarket(_db, filter = {}) {
     const params = [];
     let ownedSelect = '';
     if (filter.viewerId) {
@@ -198,29 +201,32 @@ export function listMarket(db, filter = {}) {
     }
     sql += ' ORDER BY l.total_sales DESC, l.rating DESC, l.created_at DESC LIMIT ?';
     params.push(filter.limit ?? 30);
-    return db.prepare(sql).all(...params);
+    return await dbAll(sql, params);
 }
 /** 公开详情（不含 content）；附加 owned 标记。未上架的仅作者本人可见，防 metadata 泄露 */
-export function getMarketDetail(db, id, viewerId) {
-    const row = db.prepare(`
+export async function getMarketDetail(_db, id, viewerId) {
+    const row = await dbOne(`
     SELECT ${PUBLIC_COLS}, u.name as author_name
     FROM skill_listings l JOIN users u ON l.author_id = u.id
     WHERE l.id = ?
-  `).get(id);
+  `, [id]);
     if (!row)
         return null;
     if (row.status !== 'approved' && row.author_id !== viewerId)
         return null;
-    if (viewerId)
-        row.owned = hasUnlock(db, viewerId, id) ? 1 : 0;
+    if (viewerId) {
+        // owned 检查内联(hasUnlock 被同步写路径复用,留 Phase 3;此处直接走 seam,与 hasUnlock 同 SQL)
+        const unlocked = await dbOne(`SELECT 1 FROM skill_orders o WHERE o.listing_id = ? AND o.buyer_id = ? AND o.billing_mode IN ('free','one_time') LIMIT 1`, [id, viewerId]);
+        row.owned = unlocked ? 1 : 0;
+    }
     return row;
 }
 /** 作者视角：自己的全部技能（含各状态、含 content 由调用方决定是否回传） */
-export function getMyListings(db, authorId) {
-    return db.prepare(`
+export async function getMyListings(_db, authorId) {
+    return await dbAll(`
     SELECT ${PUBLIC_COLS}, l.audit_note, l.reviewed_at, l.total_revenue
     FROM skill_listings l WHERE l.author_id = ? ORDER BY l.created_at DESC
-  `).all(authorId);
+  `, [authorId]);
 }
 // ─── 访问权 / 解锁 ────────────────────────────────────────────
 /** one_time/free 是否已永久解锁（per_use 不算永久解锁） */
@@ -303,8 +309,8 @@ export function readContent(db, userId, listingId, feeRate) {
     return { content: listing.content, billing_mode: listing.billing_mode };
 }
 /** 我的技能库：已解锁(free/one_time)的技能 + per_use 使用过的技能 */
-export function getMyLibrary(db, userId) {
-    return db.prepare(`
+export async function getMyLibrary(_db, userId) {
+    return await dbAll(`
     SELECT ${PUBLIC_COLS}, u.name as author_name, 1 as owned,
       MAX(o.created_at) as last_used
     FROM skill_orders o
@@ -313,15 +319,15 @@ export function getMyLibrary(db, userId) {
     WHERE o.buyer_id = ?
     GROUP BY l.id
     ORDER BY last_used DESC
-  `).all(userId);
+  `, [userId]);
 }
 // ─── 审计（WebAZ content admin）─────────────────────────────────
-export function listPendingAudit(db, limit = 100) {
-    return db.prepare(`
+export async function listPendingAudit(_db, limit = 100) {
+    return await dbAll(`
     SELECT l.*, u.name as author_name
     FROM skill_listings l JOIN users u ON l.author_id = u.id
     WHERE l.status = 'submitted' ORDER BY l.created_at ASC LIMIT ?
-  `).all(limit);
+  `, [limit]);
 }
 export function auditListing(db, listingId, reviewerId, decision, note) {
     const cur = getListingRaw(db, listingId);

package/dist/pwa/acp-feed.js

@@ -87,11 +87,23 @@ export function buildAcpProductFeed(db, opts = {}) {
         generated_at: new Date().toISOString(),
         source: 'WebAZ',
         spec: {
-            based_on: 'OpenAI Agentic Commerce Protocol — product feed',
+            feed_kind: 'acp-inspired-discovery',
+            based_on: 'OpenAI Agentic Commerce Protocol — product feed (SHAPE only; this is a discovery projection, not a strict ACP-ingestable merchant feed)',
             api_version_observed: '2025-09-12',
             reference: 'https://developers.openai.com/commerce/specs/feed',
             rfc: `${BASE}/docs/INTEGRATOR.md`,
         },
+        // Explicit non-compliance so an ACP ingester does NOT treat this as a strict feed (Codex #151).
+        compatibility: {
+            is_strict_acp_ingestable: false,
+            summary: 'Discovery projection that borrows the ACP product-feed shape. It is intentionally NOT a strict ACP-ingestable feed.',
+            non_compliant_points: [
+                'price.currency is SIMULATED WAZ (pre-launch internal unit), not an ISO 4217 fiat currency.',
+                'is_eligible_checkout is false for every item: ACP checkout (card + PSP) is not wired.',
+                'Merchant-level required fields (target_countries, store_country) are not emitted.',
+            ],
+            strict_export: 'A strict/export feed (ISO 4217 + merchant required fields, compliant items only) is deferred to a later RFC-015 phase, after fiat pricing + ACP checkout exist — it would be empty today.',
+        },
         _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.",

package/dist/pwa/admin-bearer-auth.js

@@ -0,0 +1,21 @@
+export function resolveBearerProtocolAdmin(db, req, isProtocolAdmin) {
+    const authz = req?.headers?.authorization;
+    if (typeof authz !== 'string' || !authz.startsWith('Bearer '))
+        return null; // Bearer only — NOT req.body.api_key
+    const key = authz.slice('Bearer '.length).trim();
+    if (!key)
+        return null;
+    const u = db.prepare('SELECT * FROM users WHERE api_key = ?').get(key);
+    if (!u)
+        return null;
+    const mod = db.prepare('SELECT suspended FROM user_moderation WHERE user_id = ?').get(u.id);
+    if (mod?.suspended)
+        return null; // suspended admin cannot approve
+    const session = db.prepare('SELECT revoked_at FROM user_sessions WHERE api_key = ? ORDER BY created_at DESC LIMIT 1')
+        .get(key);
+    if (session?.revoked_at)
+        return null; // remotely logged-out session cannot approve
+    if (!isProtocolAdmin(u))
+        return null; // admin role + protocol permission (caller-supplied, central logic)
+    return u;
+}

package/dist/pwa/contract-fingerprint.js

@@ -33,6 +33,8 @@ export function contractFingerprints() {
 export const CONTRACT_CHANGES = [
     { contract_version: 1, date: '2026-06-06', surface: 'all', kind: 'genesis', summary: 'Contract v1 baseline: capability matrix (§②), entity dictionary + order lifecycle (§①), event cursor stream (§⑥), two version axes (§④).' },
     { contract_version: 2, date: '2026-06-06', surface: 'entity', kind: 'added', summary: '§① entity dictionary gains product + dispute entities (conservative public fields; dispute = redacted dispute_cases) + goal_index pointer. Additive — existing order entity unchanged; agents may ignore.' },
+    { 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.' },
 ];
 export function buildChangeFeed() {
     return {

package/dist/pwa/email-delivery.js

@@ -0,0 +1,127 @@
+const DEFAULT_FROM = 'WebAZ <noreply@webaz.xyz>';
+const DEFAULT_BASE_URL = 'https://webaz.xyz';
+export function emailDeliveryNotConfigured() {
+    return {
+        ok: false,
+        status: 503,
+        error_code: 'EMAIL_DELIVERY_NOT_CONFIGURED',
+        error: '邮箱发送服务未配置，请稍后再试',
+    };
+}
+export function emailDeliveryFailed() {
+    return {
+        ok: false,
+        status: 502,
+        error_code: 'EMAIL_DELIVERY_FAILED',
+        error: '验证码邮件发送失败，请稍后再试',
+    };
+}
+function isProtectedEmailEnv(env) {
+    return env.NODE_ENV === 'production'
+        || !!env.RAILWAY_ENVIRONMENT
+        || !!env.RAILWAY_PROJECT_ID
+        || !!env.RAILWAY_SERVICE_ID;
+}
+export function isVerificationEmailReady(env = process.env) {
+    if (!isProtectedEmailEnv(env))
+        return true;
+    return !!env.RESEND_API_KEY?.trim();
+}
+function purposeText(purpose) {
+    if (purpose === 'register')
+        return { zh: '注册账户（验证邮箱）', en: 'register your account (verify email)' };
+    if (purpose === 'bind_email')
+        return { zh: '绑定邮箱', en: 'bind your email address' };
+    if (purpose === 'recover_key')
+        return { zh: '找回密钥', en: 'recover your account key' };
+    if (purpose.startsWith('withdraw_confirm'))
+        return { zh: '确认提现', en: 'confirm a withdrawal' };
+    return { zh: '验证身份', en: 'verify your identity' };
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, c => ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+    }[c] || c));
+}
+export function buildVerificationEmail(input) {
+    const purpose = purposeText(input.purpose);
+    const baseUrl = input.baseUrl?.trim() || DEFAULT_BASE_URL;
+    const subject = 'WebAZ 验证码 / Verification code';
+    const text = [
+        `WebAZ 验证码: ${input.code}`,
+        '',
+        `用途: ${purpose.zh}`,
+        `有效期: ${input.ttlMin} 分钟`,
+        '',
+        `Your WebAZ verification code is ${input.code}.`,
+        `Use it to ${purpose.en}. It expires in ${input.ttlMin} minutes.`,
+        '',
+        'If you did not request this code, you can ignore this email.',
+        baseUrl,
+    ].join('\n');
+    const html = [
+        '<div style="font-family:system-ui,-apple-system,Segoe UI,sans-serif;line-height:1.5;color:#111827">',
+        '<h2 style="margin:0 0 12px">WebAZ verification code</h2>',
+        `<p style="margin:0 0 8px">用途: ${escapeHtml(purpose.zh)} / ${escapeHtml(purpose.en)}</p>`,
+        `<p style="font-size:28px;font-weight:700;letter-spacing:4px;margin:16px 0">${escapeHtml(input.code)}</p>`,
+        `<p style="margin:0 0 8px">有效期 ${input.ttlMin} 分钟 / Expires in ${input.ttlMin} minutes.</p>`,
+        '<p style="margin:16px 0 0;color:#6b7280">If you did not request this code, you can ignore this email.</p>',
+        `<p style="margin:16px 0 0"><a href="${escapeHtml(baseUrl)}">${escapeHtml(baseUrl)}</a></p>`,
+        '</div>',
+    ].join('');
+    return { subject, text, html };
+}
+export async function deliverVerificationCode(input) {
+    const env = input.env || process.env;
+    const logger = input.logger || console;
+    if (!isProtectedEmailEnv(env)) {
+        logger.log(`[verify] ${input.purpose} -> ${input.target}  code=${input.code}  (expires ${input.ttlMin}min)`);
+        return { ok: true, provider: 'dev_console' };
+    }
+    const apiKey = env.RESEND_API_KEY?.trim();
+    if (!apiKey)
+        return emailDeliveryNotConfigured();
+    const fetchImpl = input.fetchImpl || globalThis.fetch;
+    if (!fetchImpl)
+        return emailDeliveryNotConfigured();
+    const baseUrl = env.WEBAZ_PUBLIC_URL?.trim() || env.PUBLIC_BASE_URL?.trim() || DEFAULT_BASE_URL;
+    const email = buildVerificationEmail({
+        code: input.code,
+        purpose: input.purpose,
+        ttlMin: input.ttlMin,
+        baseUrl,
+    });
+    const body = {
+        from: env.EMAIL_FROM?.trim() || DEFAULT_FROM,
+        to: [input.target],
+        subject: email.subject,
+        text: email.text,
+        html: email.html,
+    };
+    const replyTo = env.EMAIL_REPLY_TO?.trim();
+    if (replyTo)
+        body.reply_to = replyTo;
+    try {
+        const response = await fetchImpl('https://api.resend.com/emails', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            logger.warn(`[verify] resend delivery failed: status=${response.status} purpose=${input.purpose}`);
+            return emailDeliveryFailed();
+        }
+        return { ok: true, provider: 'resend' };
+    }
+    catch {
+        logger.warn(`[verify] resend delivery failed: network purpose=${input.purpose}`);
+        return emailDeliveryFailed();
+    }
+}

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' },
+    // 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' },
     // #1115 P1:写 PII(收货地址)。原为 (addresses OR profile/default-address);拆两条等价规则,顺序保持。
     { method: 'WRITE', re: /^\/api\/addresses(\/|$)/, action: 'set_address' },
     { method: 'WRITE', exact: '/api/profile/default-address', action: 'set_address' },
@@ -55,7 +58,8 @@ export const SAFE_WRITE = [
     /^\/api\/me\/(delete-cancel|notify-claim-tasks)/,
     /^\/api\/peers\//, /^\/api\/signaling\//,
     /^\/api\/product-share\/touch$/, /^\/api\/anchor\/[^/]+\/touch$/,
-    /^\/api\/reviews\//,
+    // Codex #98 P1:不再整段放行 /api/reviews/ —— claim 是 5 WAZ 质押资金写,已上提到 WRITE_RULES(review_claim);
+    //   GET reviews(recent / :type/:id/claims)无须写 scope(GET 由 endpointToAction 返回 null,不依赖 SAFE)。
 ];
 function methodMatches(m, method) {
     if (m === 'POST')

package/dist/pwa/goal-index.js

@@ -12,29 +12,29 @@ import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
 import { capabilityMatrix } from './endpoint-actions.js';
 const GOALS = [
     // ── discover / buy ──
-    { goal: 'Find a specific product by title/SKU/exact desc', when: 'buyer knows what they want (strict match)', action: 'open', endpoint: 'GET /api/search?query=...', mcp_tool: 'webaz_search', pwa: '#buy', see: '② read scope "search"', notes: 'STRICT — no fuzzy fallback; 0 hits → guide user to #discover (fuzzy is a human action, not agent-automated).' },
-    { goal: 'Match a pasted external link (taobao/douyin/xhs/jd/...)', when: 'buyer pastes an off-site product URL', action: 'open', endpoint: 'GET /api/search?external_link=...', mcp_tool: 'webaz_search', pwa: '#buy', notes: 'matches the anchor registry product fingerprint.' },
+    { goal: 'Find a specific product by title/SKU/exact desc', when: 'buyer knows what they want (strict match)', action: 'open', endpoint: 'GET /api/products?q=...', mcp_tool: 'webaz_search', pwa: '#buy', see: '② read scope "search"', notes: 'protocol-level STRICT alias match (mode=agent), no fuzzy fallback; 0 hits → guide user to #discover (fuzzy is a human action, not agent-automated).' },
+    { goal: 'Match a pasted external link (taobao/douyin/xhs/jd/...)', when: 'buyer pastes an off-site product URL or share text', action: 'open', endpoint: 'POST /api/search-by-link', mcp_tool: 'webaz_search', pwa: '#buy', notes: 'body: { text } (raw paste of share text/URL) OR { external_link: { platform, external_id, external_title, canonical_url } }. Matches the anchor registry product fingerprint.' },
     { goal: "Browse what's popular near me / same city", when: 'geo discovery, no keyword', action: 'search', endpoint: 'GET /api/nearby', mcp_tool: 'webaz_nearby', pwa: '#nearby', see: '② read scope "search"', notes: 'k-anonymity ≥3.' },
     { goal: 'Find used / pre-owned / secondhand items', when: 'pre-owned, separate space from new catalog', action: 'open', endpoint: 'GET /api/secondhand', mcp_tool: 'webaz_secondhand', pwa: '#secondhand', notes: 'webaz_search does NOT return secondhand.' },
     { goal: 'Verify a price before buying', when: 'BEFORE every purchase', action: 'open', endpoint: 'GET /api/products/:id (+ verify)', mcp_tool: 'webaz_verify_price', pwa: '#buy', notes: 'defeats flash-sale/hidden-fee race; protocol only liable for the verified T0 price.' },
     { goal: 'Place an order (buy a catalog product)', when: 'buyer commits to purchase', action: 'place_order', endpoint: 'POST /api/orders', mcp_tool: 'webaz_place_order', pwa: '#buy', see: '① entity order · ⑧ value flow', notes: 'pass expected_price (T0 guard, 409 on drift).' },
     { goal: 'Buy a secondhand item', when: 'order a pre-owned listing', action: 'buy_secondhand', endpoint: 'POST /api/secondhand/:id/order', mcp_tool: 'webaz_secondhand', pwa: '#secondhand' },
     { goal: 'Buy a knowledge skill', when: 'purchase a prompt/template/checklist', action: 'purchase', endpoint: 'POST /api/skill-market/:id/purchase', mcp_tool: 'webaz_skill_market', pwa: '#skill-market', notes: 'content market — distinct from webaz_skill behavior plugins.' },
-    { goal: 'Bid in an auction', when: 'time-windowed price discovery on listed item', action: 'bid', endpoint: 'POST /api/auctions/:id/bid', mcp_tool: 'webaz_bid', pwa: '#auctions', notes: 'anti-snipe time extension.' },
+    { goal: 'Bid in an auction', when: 'time-windowed price discovery on listed item', action: 'bid', endpoint: 'POST /api/auctions/:id/bids', mcp_tool: 'webaz_bid', pwa: '#auctions', notes: 'anti-snipe time extension.' },
     { goal: 'Post a buy request (RFQ) for sellers to quote', when: 'no good match / bulk / custom / wants competing quotes', action: 'rfq', endpoint: 'POST /api/rfqs', mcp_tool: 'webaz_rfq', pwa: '#rfqs', notes: 'reverse match — buyer posts need + 1% stake.' },
     // ── sell / fulfill ──
-    { goal: 'List / update a product', when: 'seller publishes, edits, delists own listing', action: 'list_product', endpoint: 'POST|PUT /api/products', mcp_tool: 'webaz_list_product', pwa: '#me', see: '① entity product', notes: 'system suggests stake ~15% of price (buyer protection).' },
-    { goal: 'Fulfill an order (accept / ship / deliver / pickup)', when: 'seller or logistics advances fulfilment', action: 'fulfill', endpoint: 'POST /api/orders/:id/{accept|ship|deliver|pickup|transit}', mcp_tool: 'webaz_update_order', pwa: '#me', see: '① order lifecycle · ⑦ liability', notes: 'missing a deadline → auto fault (see order lifecycle).' },
-    { goal: 'Confirm receipt (buyer closes the order)', when: 'buyer received the goods', action: 'confirm_order', endpoint: 'POST /api/orders/:id/confirm', mcp_tool: 'webaz_update_order', pwa: '#me', notes: 'auto-confirm on confirm_deadline timeout.' },
+    { goal: 'List / update a product', when: 'seller publishes, edits, delists own listing', action: 'list_product', endpoint: 'POST /api/products · PUT /api/products/:id', mcp_tool: 'webaz_list_product', pwa: '#me', see: '① entity product', notes: 'POST creates, PUT /:id edits/delists. System suggests stake ~15% of price (buyer protection).' },
+    { goal: 'Fulfill an order (accept / ship / deliver / pickup)', when: 'seller or logistics advances fulfilment', action: 'fulfill', endpoint: 'POST /api/orders/:id/action', mcp_tool: 'webaz_update_order', pwa: '#me', see: '① order lifecycle · ⑦ liability', notes: 'single state-machine endpoint; body { action } ∈ {accept|ship|pickup|transit|deliver|confirm|dispute}. Missing a deadline → auto fault.' },
+    { goal: 'Confirm receipt (buyer closes the order)', when: 'buyer received the goods', action: 'confirm_order', endpoint: 'POST /api/orders/:id/action', mcp_tool: 'webaz_update_order', pwa: '#me', notes: 'body { action: "confirm" }. Auto-confirm on confirm_deadline timeout.' },
     // ── dispute / verify ──
     { goal: 'Respond to a dispute as a party', when: 'a counterparty opened a dispute on your order', action: 'dispute_respond', endpoint: 'POST /api/disputes/:id/respond', mcp_tool: 'webaz_dispute', pwa: '#me', see: '① entity dispute · ⑦ liability' },
     { goal: 'Look up public dispute precedents', when: 'assess a seller / understand likely ruling', action: 'open', endpoint: 'GET /api/disputes/cases (+ /by-product/:id)', mcp_tool: 'webaz_dispute', pwa: '#disputes', see: '① entity dispute', notes: 'redacted post-ruling cases; amount is bucketed.' },
     { goal: 'Verify an agent passport / external anchor / AP2 mandate', when: 'check a counterparty/data is genuine', action: 'open', endpoint: 'GET /.well-known/webaz-verifiability.json', mcp_tool: null, pwa: '(n/a)', see: '⑤ verifiability index', notes: 'offline-verifiable where signed; order-chain is integrity-only.' },
     // ── participate / social ──
     { goal: 'Become a value participant (earn/pay/stake)', when: 'integrate as seller/logistics/verifier/insurer/etc.', action: 'open', endpoint: 'GET /.well-known/webaz-economic.json', mcp_tool: null, pwa: '(n/a)', see: '⑧ economic participation', notes: 'roles + live rates + collateral + conserved liability.' },
-    { goal: 'Communicate with a trade counterparty', when: 'ask seller a question / coordinate an order', action: 'chat', endpoint: 'POST /api/conversations', mcp_tool: 'webaz_chat', pwa: '#messages', notes: 'every message attaches to a trade context — not general LLM chat.' },
+    { goal: 'Communicate with a trade counterparty', when: 'ask seller a question / coordinate an order', action: 'chat', endpoint: 'POST /api/conversations/start', mcp_tool: 'webaz_chat', pwa: '#messages', notes: 'start a thread; then POST /api/conversations/:id/messages. Every message attaches to a trade context — not general LLM chat.' },
     { goal: 'Share / refer a product for commission', when: 'promote a listing; attributed sales pay commission', action: 'share', endpoint: 'POST /api/shareables', mcp_tool: 'webaz_shareables', pwa: '#me', see: '⑧ promoter role' },
-    { goal: 'Publish or fund a charity wish / community fund', when: 'community mutual-aid', action: 'charity', endpoint: 'POST /api/wishes · POST /api/charity', mcp_tool: 'webaz_charity', pwa: '#charity', notes: 'distinct from place_order donation_pct.' },
+    { goal: 'Publish or fund a charity wish / community fund', when: 'community mutual-aid', action: 'charity', endpoint: 'POST /api/wishes', mcp_tool: 'webaz_charity', pwa: '#charity', notes: 'publish a wish; fund the shared pool via POST /api/charity/fund/donate. Distinct from place_order donation_pct.' },
     { goal: 'Donate to the community fund', when: 'contribute to the shared fund', action: 'donate', endpoint: 'POST /api/charity/fund/donate', mcp_tool: 'webaz_charity', pwa: '#charity' },
     // ── self state ──
     { goal: 'Set a shipping address (PII write)', when: 'before a shipped order', action: 'set_address', endpoint: 'POST /api/addresses', mcp_tool: 'webaz_default_address', pwa: '#me', see: '② write_action set_address (元规则#3 PII gate)' },

package/dist/pwa/human-presence.js

@@ -0,0 +1,62 @@
+export function createHumanPresence(db, getProtocolParam) {
+    // 验证 gate token:被业务端点(如 /api/wallet/withdraw)消费。
+    // M-1: 改 CAS — 先抢占性 UPDATE,只有 changes=1 才认为本次成功消费;然后再读 row 校验
+    // user/purpose/业务字段。多副本部署也安全。
+    function consumeGateToken(userId, token, purpose, validate) {
+        if (!token)
+            return { ok: false, reason: '缺少 X-WebAuthn-Token' };
+        // 先抢占:未消费 + 未过期 才能 mark consumed
+        const claim = db.prepare(`UPDATE webauthn_gate_tokens
+      SET consumed_at = datetime('now')
+      WHERE id = ? AND consumed_at IS NULL AND expires_at > datetime('now')`).run(token);
+        if (claim.changes !== 1) {
+            // 抢占失败的两种原因区分(仅用于 reason 文案)
+            const exist = db.prepare('SELECT consumed_at FROM webauthn_gate_tokens WHERE id = ?').get(token);
+            if (!exist)
+                return { ok: false, reason: 'token 不存在' };
+            if (exist.consumed_at)
+                return { ok: false, reason: 'token 已使用' };
+            return { ok: false, reason: 'token 已过期' };
+        }
+        // 已抢占 → 读 row 校验 user/purpose/业务字段;若校验失败 token 仍然作废(防止枚举攻击下的重试)
+        const row = db.prepare(`SELECT user_id, purpose, purpose_data FROM webauthn_gate_tokens WHERE id = ?`)
+            .get(token);
+        if (row.user_id !== userId)
+            return { ok: false, reason: 'token 用户不匹配' };
+        if (row.purpose !== purpose)
+            return { ok: false, reason: 'token 用途不匹配' };
+        let data = null;
+        try {
+            data = row.purpose_data ? JSON.parse(row.purpose_data) : null;
+        }
+        catch { }
+        if (!validate(data))
+            return { ok: false, reason: 'token 业务参数不匹配' };
+        return { ok: true };
+    }
+    // ─── Agent 治理铁律:人工铁律节点 ───
+    // 关键节点(verifier 投票 / arbitrator 仲裁 / agent_revoke / delete_passkey / identity_claim)必须真实
+    // 人工参与,agent 代操作被拦截。实现:要求 webauthn_gate_token(一次性 · 60s)+ 协议参数开关。
+    // is_system fixture 旁路只对 vote/arbitrate 生效(有白名单表);其余无豁免。
+    function requireHumanPresence(userId, purpose, token, paramKey, validate = () => true) {
+        const enabled = Number(getProtocolParam(paramKey, 1)) === 1;
+        if (!enabled)
+            return { ok: true }; // 协议参数关闭 → 不强制
+        if (purpose === 'vote') {
+            const wl = db.prepare('SELECT is_system FROM verifier_whitelist WHERE user_id = ?').get(userId);
+            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 };
+        }
+        return { ok: true };
+    }
+    return { consumeGateToken, requireHumanPresence };
+}