@seasonkoh/webaz 0.1.19 → 0.1.21

package/dist/pwa/routes/public-utils.js

@@ -1,3 +1,15 @@
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../../version.js';
+import { capabilityMatrix } from '../endpoint-actions.js';
+import { buildEntityDictionary } from '../entity-dictionary.js';
+import { buildGoalIndex } from '../goal-index.js';
+import { buildChangeFeed } from '../contract-fingerprint.js';
+import { buildIntegrationContract } from '../integration-contract.js';
+import { buildVerifiabilityIndex } from '../verifiability-index.js';
+import { buildEconomicParticipation } from '../economic-participation.js';
+import { buildNegativeSpace } from '../negative-space.js';
 export function registerPublicUtilsRoutes(app, deps) {
     const { db, MASTER_SEED, NODE_ENV, SERVICE_START_MS, rateLimitOk, generateManifest, getUser, logError, issuerAddress } = deps;
     app.get('/api/health', (_req, res) => {
@@ -73,7 +85,11 @@ export function registerPublicUtilsRoutes(app, deps) {
         const issuerActiveSince = db.prepare("SELECT value FROM system_state WHERE key='issuer_active_since'").get()?.value || '2026-05-30';
         return {
             name: 'WebAZ Protocol',
-            schema_version: 1,
+            // RFC-011 §④ 两轴版本(单一来源 src/version.ts):
+            //   schema_version  = 集成契约版本(整数,仅 breaking 契约变更才 bump;集成方 agent 按此判兼容)
+            //   software_version = 本代码 npm/release semver(= package.json,自动同步,永不漂移)
+            schema_version: CONTRACT_VERSION,
+            software_version: SOFTWARE_VERSION,
             network_state: {
                 phase,
                 real_users_on_canonical: realUsers,
@@ -106,6 +122,22 @@ export function registerPublicUtilsRoutes(app, deps) {
                 agent_governance: 'https://github.com/seasonsagents-art/webaz/blob/main/docs/AGENT-GOVERNANCE.md',
                 protocol_compatibility: 'https://github.com/seasonsagents-art/webaz/blob/main/docs/PROTOCOL-COMPATIBILITY-AUDIT-2026-05-30.md',
                 changelog: 'https://github.com/seasonsagents-art/webaz/blob/main/CHANGELOG.md',
+                // RFC-011 §②:agent 可读能力矩阵(写边界 action-scope + 敏感读 scope),live doc=code
+                capability_matrix: 'https://webaz.xyz/.well-known/webaz-capabilities.json',
+            },
+            // RFC-011 agent 接入 live 端点;总入口 integration.json 把它们按旅程串起来
+            agent_endpoints: {
+                integration_contract: 'https://webaz.xyz/.well-known/webaz-integration.json', // RFC-011 总入口(按旅程导航全维度)
+                capability_matrix: 'https://webaz.xyz/.well-known/webaz-capabilities.json', // ② 边界(#126)
+                entity_dictionary: 'https://webaz.xyz/.well-known/webaz-entities.json', // ① 语义(order/product/dispute 状态机 + 字段)
+                goal_index: 'https://webaz.xyz/.well-known/webaz-goals.json', // ① 目标索引(intent → action + endpoint + 工具)
+                change_feed: 'https://webaz.xyz/api/agent/changes', // ④ 契约变更 + 指纹 + 弃用
+                verifiability_index: 'https://webaz.xyz/.well-known/webaz-verifiability.json', // ⑤ 什么可验+怎么验
+                economic_participation: 'https://webaz.xyz/.well-known/webaz-economic.json', // ⑧ value-participant 角色经济条款(费率实时)
+                negative_space: 'https://webaz.xyz/.well-known/webaz-negative-space.json', // ② 负空间(禁区 + 限额 + 后果阶梯)
+                event_stream: 'https://webaz.xyz/api/agent/events?since=<cursor>', // ⑥ 事件游标流(party-gated,需 auth)
+                passport: 'https://webaz.xyz/api/me/agents/:apiKeyPrefix/passport', // ⑤ 可验护照
+                did: 'https://webaz.xyz/.well-known/did.json',
             },
             // 路线图 — 回应"知道还有哪些没做"的诚实化第三层。哲学:公开当前到达点 + 已知未做项,不承诺时间表。
             roadmap: {
@@ -140,6 +172,104 @@ export function registerPublicUtilsRoutes(app, deps) {
         res.setHeader('Cache-Control', 'public, max-age=300');
         res.json(buildProtocolManifest());
     });
+    // RFC-011 §② — agent 可读能力矩阵(写边界 action-scope + 敏感读 scope)。
+    //   live = 直接序列化 enforce 用的规则表(src/pwa/endpoint-actions.ts),doc=code 零漂移。
+    //   集成方 agent fetch 此端点即知"我要做的写需要声明哪个 scope / 哪些写无需 scope / 哪些读受约束"。
+    app.get('/.well-known/webaz-capabilities.json', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(capabilityMatrix());
+    });
+    app.get('/api/agent/capabilities', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(capabilityMatrix());
+    });
+    // RFC-011 §① — agent 可读实体字典(订单状态机 doc=code + 保守公开字段 + 可验证标注)。
+    app.get('/.well-known/webaz-entities.json', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildEntityDictionary());
+    });
+    app.get('/api/agent/entities', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildEntityDictionary());
+    });
+    // RFC-011 §① 目标索引 —— intent → action(②)+ endpoint + MCP 工具 + PWA 页(agent 自路由)。
+    app.get('/.well-known/webaz-goals.json', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildGoalIndex());
+    });
+    // 集成必需文档(规则 + onboarding)由协议自身 serve —— 外部 agent 必须能读到约束它的规则,
+    //   不能指向私有 repo 的 GitHub(对外 404)。显式白名单:只暴露这 3 份"本就该公开"的文档,
+    //   非白名单 → 404(不泄漏 RFC/审计等内部设计文档;它们是 provenance,随 repo 公开解锁)。
+    const PUBLIC_DOCS = new Set(['INTEGRATOR.md', 'META-RULES-FULL.md', 'ECONOMIC-MODEL.md']);
+    const DOCS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../docs'); // repo-root/docs(dev+prod 都解析到此)
+    app.get('/docs/:name', (req, res) => {
+        const name = String(req.params.name);
+        if (!PUBLIC_DOCS.has(name))
+            return void res.status(404).json({ error: 'not a public doc', public_docs: [...PUBLIC_DOCS] });
+        try {
+            const md = readFileSync(path.join(DOCS_DIR, name), 'utf8');
+            res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+            res.setHeader('Cache-Control', 'public, max-age=300');
+            res.send(md);
+        }
+        catch {
+            res.status(404).json({ error: 'doc unavailable' });
+        }
+    });
+    app.get('/api/agent/goals', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildGoalIndex());
+    });
+    // RFC-011 §④ — 契约变更 feed:current_contract_version + 契约面指纹 + 变更注册表 + 弃用策略。
+    //   agent 用上次见过的 contract_version poll;指纹让它不必 diff 整份契约就知道有没有漂移。
+    //   指纹由 tests/test-contract-fingerprint.ts + docs/CONTRACT-LOCK.json 守住(静默改契约不可 merge)。
+    app.get('/api/agent/changes', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildChangeFeed());
+    });
+    // RFC-011 总入口 —— 集成方 agent 一次 fetch 拿到整份契约导航(按旅程组织,指向各维度 live 端点)。
+    app.get('/.well-known/webaz-integration.json', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildIntegrationContract());
+    });
+    app.get('/api/agent/integration', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildIntegrationContract());
+    });
+    // RFC-011 §⑤ 可验证索引 —— "什么可验 + 怎么验"统一表(护照/锚/AP2/订单链),诚实分级。
+    app.get('/.well-known/webaz-verifiability.json', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildVerifiabilityIndex());
+    });
+    app.get('/api/agent/verifiability', (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildVerifiabilityIndex());
+    });
+    // RFC-011 §⑧ 经济参与索引 —— value-participant 角色 × 赚什么/押什么/担什么责,
+    //   费率【实时】从 protocol_params 读(doc=code,永不和 enforced 经济漂移)。
+    const liveParam = (key, fallback) => {
+        const row = db.prepare('SELECT value, type FROM protocol_params WHERE key = ?').get(key);
+        if (!row)
+            return fallback;
+        if (row.type === 'number')
+            return Number(row.value);
+        if (row.type === 'boolean')
+            return (row.value === 'true' || row.value === '1');
+        return row.value;
+    };
+    const economic = (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildEconomicParticipation(liveParam));
+    };
+    app.get('/.well-known/webaz-economic.json', economic);
+    app.get('/api/agent/economic-participation', economic);
+    // RFC-011 §② 负空间 —— 禁区 + enforced 限额 + 后果阶梯(per-agent 速率实时读)。
+    const negativeSpace = (_req, res) => {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+        res.json(buildNegativeSpace(liveParam));
+    };
+    app.get('/.well-known/webaz-negative-space.json', negativeSpace);
+    app.get('/api/agent/negative-space', negativeSpace);
     // W3C DID Document(B.6 b DID 短期 mapping,2026-05-30):
     //   did:web:webaz.xyz 通过 HTTPS 解析到这里(W3C did:web spec §3.2)
     //   verificationMethod 用 EcdsaSecp256k1RecoveryMethod2020 + CAIP-10 blockchainAccountId

package/dist/pwa/routes/webauthn.js

@@ -1,5 +1,7 @@
 import { generateRegistrationOptions, verifyRegistrationResponse, generateAuthenticationOptions, verifyAuthenticationResponse, } from '@simplewebauthn/server';
 import { randomBytes } from 'node:crypto';
+// RFC-004 体验补:绑定 Passkey 后,追溯补发此前"已受理但无锚点跳过"的建设信誉。
+import { grantPendingAnchorCredits } from '../../layer2-business/L2-8-feedback/build-feedback-engine.js';
 export function registerWebauthnRoutes(app, deps) {
     const { db, auth, generateId, rpId, rpName, origin, challengeTtlMs, gateTtlMs, invalidateAgentRiskCacheForUser, requireHumanPresence } = deps;
     // 1. 注册：start — 生成 challenge + 选项
@@ -53,7 +55,13 @@ export function registerWebauthnRoutes(app, deps) {
                 .run(credential.id, user.id, Buffer.from(credential.publicKey), credential.counter || 0, JSON.stringify(credential.transports || []), (device_label || '').slice(0, 60) || null);
             db.prepare("UPDATE webauthn_challenges SET consumed_at = datetime('now') WHERE id = ?").run(challenge_id);
             invalidateAgentRiskCacheForUser(user.id); // 让 D2b 中间件立刻看到刚绑的 Passkey,否则 5min 缓存窗内仍被拦
-            res.json({ success: true, credential_id: credential.id });
+            // RFC-004:绑定 Passkey = 成为可问责真人 → 追溯补发此前因无锚点跳过的建设信誉(advisory,永不阻塞绑定)
+            let backfilled;
+            try {
+                backfilled = grantPendingAnchorCredits(db, user.id);
+            }
+            catch { /* 不影响绑定主流程 */ }
+            res.json({ success: true, credential_id: credential.id, ...(backfilled && backfilled.granted > 0 ? { build_credit_backfilled: backfilled } : {}) });
         }
         catch (e) {
             res.status(400).json({ error: e.message });

package/dist/pwa/server.js

@@ -20,7 +20,9 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import crypto from 'crypto';
 import { initDatabase, generateId } from '../layer0-foundation/L0-1-database/schema.js';
-import { initSystemUser, transition, getOrderStatus, checkTimeouts } from '../layer0-foundation/L0-2-state-machine/engine.js';
+import { initSystemUser, transition, getOrderStatus, checkTimeouts, settleFault } from '../layer0-foundation/L0-2-state-machine/engine.js';
+import { endpointToAction, endpointToReadAction } from './endpoint-actions.js';
+import { AGENT_RATE_PER_MIN_DEFAULTS, CROSS_USER_READ_DAILY_CAP, MASS_ACTION_TYPES, MASS_ACTION_DAILY_CAPS } from './limits.js';
 import { initOrderChainSchema, appendOrderEvent, getOrderChain, verifyOrderChain } from '../layer0-foundation/L0-2-state-machine/order-chain.js';
 import { initSnfSchema, snfSend, snfCleanup } from '../layer2-business/L2-7-snf/snf-engine.js';
 import { initExternalAnchorSchema } from '../layer1-agent/L1-2-external-anchor/anchor-engine.js';
@@ -534,6 +536,15 @@ for (const stmt of [
     // RFC-008 stage 1：每单【赔付背书】快照 = 该单实际背书的卖家质押额。
     //   起步免赔付阶段(require_seller_stake=0)= 0;违约结算只按此数没收,绝不扣未背书的钱 → 根治印钱 bug。
     'ALTER TABLE orders ADD COLUMN stake_backing REAL DEFAULT 0',
+    // RFC-007 stage 2：卖家【主动拒单】记录(vs 沉默超时)。reason_code 供 stage 3/5 判定客观/主观。
+    'ALTER TABLE orders ADD COLUMN decline_reason_code TEXT',
+    'ALTER TABLE orders ADD COLUMN declined_at TEXT',
+    // RFC-007 stage 3：客观理由拒单 → 【临时判责】(provisional)。先不结算,给卖家举证窗口(stage 5 仲裁翻案)。
+    //   pending=1 + deadline 到期仍无人仲裁 → checkTimeouts 终结为违约(settleFault)。stage 5 仲裁维持则翻 declined_nofault。
+    'ALTER TABLE orders ADD COLUMN decline_objective_pending INTEGER DEFAULT 0',
+    'ALTER TABLE orders ADD COLUMN decline_contest_deadline TEXT',
+    // RFC-007 stage 5：卖家已就临时判责发起仲裁举证 → 暂停 checkTimeouts 自动终结,等人工仲裁裁决。
+    'ALTER TABLE orders ADD COLUMN decline_contested INTEGER DEFAULT 0',
 ]) {
     try {
         db.exec(stmt);
@@ -778,6 +789,13 @@ const DEFAULT_PARAMS = [
     { key: 'fund_base_rate', value: '0', type: 'number', description: '协议基金池基础费率（RFC-008 硬帽 1%;pre-launch 减免=0,有真实 GMV 再由治理开启 ≤1%）', category: 'fee', min: 0, max: 0.01 },
     // RFC-008:起步免赔付门槛。0 = bootstrap(新商家零质押、违约免赔付只退款+掉信誉,降进入门槛);1 = 要求卖家质押(下单锁 stake、违约真没收)。上轨道后由治理开启。
     { key: 'require_seller_stake', value: '0', type: 'number', description: 'RFC-008 是否要求卖家质押(0=起步免赔付/零门槛,1=要求质押/真没收)', category: 'fee', min: 0, max: 1 },
+    // RFC-008 stage 2:违约罚没率,【与质押率解耦】(低质押=低摩擦 + 高罚没=强威慑,单一费率做不到)。
+    //   背书订单:penalty = fault_penalty_rate × total,先扣 staked(封顶背书)再扣自由 balance(责任自负,真可执行)。
+    //   起步免赔付(stake_backing=0):仍 0 没收,绝不碰新商家自由余额。settleFault 按订单 stake_backing 判定。
+    { key: 'fault_penalty_rate', value: '0.30', type: 'number', description: 'RFC-008 违约罚没率(与质押率解耦;背书订单 staked 不足扣自由 balance;起步免赔付订单不适用)', category: 'fee', min: 0, max: 0.50 },
+    // RFC-007 stage 3：客观理由拒单的【举证窗口】小时数。卖家声称客观无责拒单 → 临时判责,此窗口内可开仲裁(stage 5)举证;
+    //   到期无人仲裁 → 自动终结为违约。窗口内买家 escrow 暂不退(随终结/翻案一次性结算),0=不给窗口(直接违约)。
+    { key: 'decline_contest_window_hours', value: '24', type: 'number', description: 'RFC-007 客观拒单举证窗口(小时);到期未仲裁则终结为违约', category: 'limit', min: 0, max: 168 },
     { key: 'checkin_base_reward', value: '0.5', type: 'number', description: '每日签到基础奖励 WAZ', category: 'reward', min: 0, max: 10 },
     { key: 'streak_bonus_7', value: '5', type: 'number', description: '7 天里程碑额外奖励', category: 'reward', min: 0, max: 100 },
     { key: 'streak_bonus_30', value: '20', type: 'number', description: '30 天里程碑额外奖励', category: 'reward', min: 0, max: 500 },
@@ -5160,23 +5178,19 @@ function issueAgentStrike(opts) {
 void issueAgentStrike;
 function getAgentRateCap(level) {
     const key = `agent_rate_${level}_per_min`;
-    return Number(getProtocolParam(key, level === 'legend' ? 1200 : level === 'quality' ? 600 : level === 'trusted' ? 300 : 120));
+    return Number(getProtocolParam(key, AGENT_RATE_PER_MIN_DEFAULTS[level] ?? AGENT_RATE_PER_MIN_DEFAULTS.new));
 }
 // 2026-05-23 P1 fix 2.4：mass-action 日 cap（按 trust level + action 类别）
 // 拦截 spam / 信息轰炸：chat / comment / share 三类 social-write 操作有独立的日上限
 // 触发：超 cap → 429 AGENT_DAILY_CAP；累计 ≥3 次超限 / 24h → issueAgentStrike(warning)
-const MASS_ACTION_TYPES = new Set(['chat', 'comment', 'share']);
-const massActionDailyCaps = {
-    // [action][level] = daily cap
-    chat: { new: 30, trusted: 100, quality: 300, legend: 1000 },
-    comment: { new: 20, trusted: 60, quality: 150, legend: 500 },
-    share: { new: 10, trusted: 30, quality: 100, legend: 300 },
-};
+// 限额表抽到 ./limits.ts(单一真相源,与 RFC-011 §② negative-space 发布面共享)。
+const MASS_ACTION_TYPES_SET = new Set(MASS_ACTION_TYPES);
+const massActionDailyCaps = MASS_ACTION_DAILY_CAPS;
 // in-memory 日窗口 counter（不持久化，重启清零；持久化需求未来用 agent_call_log 算）
 const massActionDailyBuckets = new Map();
 function todayKey() { return new Date().toISOString().slice(0, 10); }
 function checkMassActionCap(apiKey, action, level) {
-    if (!MASS_ACTION_TYPES.has(action))
+    if (!MASS_ACTION_TYPES_SET.has(action))
         return { ok: true };
     const cap = (massActionDailyCaps[action] || {})[level] ?? massActionDailyCaps[action]?.new ?? 999999;
     const today = todayKey();
@@ -5207,13 +5221,7 @@ function checkMassActionCap(apiKey, action, level) {
 //   · 防"枚举/扒数据"型读取(剽窃 / 内容农场 / 用户画像批量化)
 //   · 真人监护人(绑 Passkey) 也罩:audit "补 A" — 之前 Passkey 真人无任何 read cap,scraper 拿真人账号即绕过
 //   · 不打 /api/nearby /api/search(地理聚合 / 关键词查),那些已被 B1 read-scope 约束
-const CROSS_USER_READ_DAILY_CAP = {
-    passkey_human: 300, // 真人监护人 — 高但有上限(每天看 300 个不同用户已属异常使用)
-    legend: 200, // 高信誉 agent
-    quality: 100,
-    trusted: 60,
-    new: 30, // 新 agent — 30 个就该有声誉再说
-};
+// CROSS_USER_READ_DAILY_CAP 抽到 ./limits.ts(单一真相源)。
 const crossUserReadBuckets = new Map();
 function extractCrossUserTarget(path, currentUserId) {
     // /api/users/:id 或 /api/users/:id/anything → :id;同 user 不算跨;sys_* 协议账号不算
@@ -5248,107 +5256,10 @@ function checkCrossUserReadCap(userId, targetId, level) {
 }
 // 2026-05-23 P0 audit fix 2.2：endpoint → action 映射（用于 declared_scope enforcement）
 // 只对写操作 enforce；读操作不限制（任何 agent 都能读自己范围内的数据）
-function endpointToAction(method, path) {
-    if (method === 'GET')
-        return null;
-    if (method === 'POST' && path === '/api/orders')
-        return 'place_order';
-    if ((method === 'POST' || method === 'PUT') && /^\/api\/products(\/[^/]+)?$/.test(path))
-        return 'list_product';
-    if (method === 'POST' && /^\/api\/orders\/[^/]+\/(accept|ship|deliver|pickup|transit)/.test(path))
-        return 'fulfill';
-    if (method === 'POST' && /^\/api\/orders\/[^/]+\/confirm/.test(path))
-        return 'confirm_order';
-    if (method === 'POST' && /^\/api\/claim-tasks\/[^/]+\/vote/.test(path))
-        return 'vote';
-    if (method === 'POST' && /^\/api\/disputes\/[^/]+\/arbitrate/.test(path))
-        return 'arbitrate';
-    if (method === 'POST' && /^\/api\/disputes\/[^/]+\/respond/.test(path))
-        return 'dispute_respond';
-    if (method === 'POST' && /^\/api\/charity\/fund\/donate/.test(path))
-        return 'donate';
-    if (method === 'POST' && /^\/api\/(wishes|charity)/.test(path))
-        return 'charity';
-    if (method === 'POST' && /^\/api\/shareables/.test(path))
-        return 'share';
-    if (method === 'POST' && /^\/api\/conversations/.test(path))
-        return 'chat';
-    if (method === 'POST' && path === '/api/skills')
-        return 'list_skill';
-    if (method === 'POST' && /^\/api\/rfqs/.test(path))
-        return 'rfq';
-    if (method === 'POST' && /^\/api\/auctions\/[^/]+\/bid/.test(path))
-        return 'bid';
-    // 权限审计 #1115 P0:花钱/价值写纳入问责门(与 place_order 同档:无 Passkey 须声明 scope)。
-    // 之前这些漏在 default-allow 之外,无声明无 Passkey 的 agent 可花掉账户余额 —— 补齐一致性。
-    if (method === 'POST' && /^\/api\/skill-market\/[^/]+\/purchase/.test(path))
-        return 'purchase';
-    if (method === 'POST' && /^\/api\/secondhand\/[^/]+\/order/.test(path))
-        return 'buy_secondhand';
-    if (method === 'POST' && /^\/api\/group-buys\/[^/]+\/join/.test(path))
-        return 'group_buy_join';
-    // #1115 P1:写 PII(收货地址)也需问责。含 addresses 增删改 + profile 默认地址。
-    if (method !== 'GET' && (/^\/api\/addresses(\/|$)/.test(path) || path === '/api/profile/default-address'))
-        return 'set_address';
-    // #1115 P2:钱包写(转出/充值/白名单/连接)统一纳入 'wallet' 问责门。
-    // 之前 wallet/* 整段在 SAFE 放行 → api_key agent 可直达 withdraw,小额零真人门分批盗刷;
-    // 现要求声明 'wallet' scope(或 '*' / Passkey)。withdraw 另在 handler 内强制 Passkey 真人门(铁律,见 wallet-write.ts)。
-    if (method !== 'GET' && /^\/api\/wallet\//.test(path))
-        return 'wallet';
-    // #1115 P2:profile **PII/身份/接管向量**写纳入 'set_profile' —— 仅这一子集需问责。
-    //   改恢复邮箱(bind/confirm-email)=账户接管;改 handle/name=身份;set/clear-location=地理 PII。
-    //   ⚠️ 不一刀切整段 profile/*:role/region/placement/password/verify 是"无 Passkey 也要能用"的
-    //   自助操作(见原则:没身份验证也要解决的问题不要求身份),它们留在下方 SAFE。
-    //   default-address 已在上面归 set_address(更具体,优先)。
-    if (method !== 'GET' && /^\/api\/profile\/(bind-email|confirm-email|change-handle|change-name|set-location|clear-location)$/.test(path))
-        return 'set_profile';
-    // ── #1115 B4 结构性:default-deny ──────────────────────────────
-    // 上面是细粒度命名 token;下面 safe-list 放行(返回 null),其余一切写 → 'write'(需 Passkey 或声明 scope)。
-    // 目的:新增的敏感写默认就被门控,不会因"忘了加映射"而裸奔(把 default-allow 翻成 default-deny)。
-    // safe-list 三类必须放行(否则误伤 / 死锁):
-    //   (a) 脱困入口:绑 Passkey(webauthn)/ 声明 scope(me/agents)/ 登录注册/找回 —— 若门控则永远无法获得通行资格
-    //   (b) 自带门:build-feedback(分级门)/ admin(requireAdmin)。
-    //       注意:wallet / profile 不再 SAFE —— #1115 P2 移到上方命名 token(wallet / set_profile / set_address)。
-    //   (c) 公开 + 低值自我状态写(管理自己的 cart/wishlist/通知/关注 等,登录即可)
-    const SAFE = [
-        // (a) 脱困 / 鉴权 / 身份(bootstrap 通行资格所必需 —— wallet 与 profile 的 PII 子集不在此列,见上方命名 token)
-        /^\/api\/(login|register)$/, /^\/api\/recover-key/, /^\/api\/webauthn\//,
-        /^\/api\/me\/agents\//,
-        // profile 自助子集(无 Passkey 真人也要能用:切角色/选地区/PV 配置/改密码/二次确认)。
-        // PII/身份子集(bind-email/change-handle/set-location 等)已在上方归 set_profile,不在此放行。
-        /^\/api\/profile\/(switch-role|add-role|region|placement-pref|bind-placement|feed-visible|verify-password|set-password|remove-password)$/,
-        // (b) 自带门(build-feedback=分级门;build-tasks=协调层登录即可;admin=requireAdmin。wallet/profile 已移到上方命名 token #1115 P2)
-        /^\/api\/build-feedback/, /^\/api\/build-tasks/, /^\/api\/admin\//,
-        // (c) 公开 / 无需登录
-        /^\/api\/(public-ideas|error-report|mcp-telemetry|email-subscriptions|search-by-link|feedback)(\/|$)/,
-        // (c) 低值自我状态
-        /^\/api\/cart$/, /^\/api\/cart\/(?!checkout)[^/]+$/,
-        /^\/api\/wishlist/, /^\/api\/products\/[^/]+\/waitlist$/,
-        /^\/api\/notifications\/read$/, /^\/api\/announcements\/[^/]+\/read$/,
-        /^\/api\/follows\//, /^\/api\/blocklist\//,
-        /^\/api\/checkin$/, /^\/api\/growth\/tasks\//, /^\/api\/tasks\/[^/]+\/claim$/,
-        /^\/api\/push\//, /^\/api\/auth\//,
-        /^\/api\/me\/(delete-cancel|notify-claim-tasks)/,
-        /^\/api\/peers\//, /^\/api\/signaling\//,
-        /^\/api\/product-share\/touch$/, /^\/api\/anchor\/[^/]+\/touch$/,
-        /^\/api\/reviews\//,
-    ];
-    if (SAFE.some(r => r.test(path)))
-        return null;
-    return 'write'; // 默认拒绝:其余写需问责
-}
-// Phase 3b（B1）：敏感读 → read-scope token 映射。只挑「跨用户聚合 / 批量扫描」这类剽窃向读取，
-// 普通读（自己的 profile / products 列表 / 订单等）一律 null 不约束，避免误伤声明 agent 的日常读。
-// 仅对「有声明」的 agent 生效（见中间件）；真人 / 无声明 / 通配 '*' 都不受此约束。
-function endpointToReadAction(path) {
-    if (/^\/api\/nearby/.test(path))
-        return 'search'; // 雷达扫描（地理聚合）
-    if (/^\/api\/search/.test(path))
-        return 'search'; // 模糊搜索深翻页
-    if (/^\/api\/users\/[^/]+\//.test(path))
-        return 'profile'; // 他人主页 / 信誉 / 内容流（枚举剽窃向）
-    return null;
-}
+// RFC-011 §②:写边界分类器 + 敏感读 scope 已抽到 src/pwa/endpoint-actions.ts(声明式规则表,
+//   同一份规则既 enforce(此处中间件迭代)又 publish(capabilityMatrix 端点),doc=code。
+//   行为零变化由 tests/test-endpoint-actions.ts 锁定(420 组 path×method diff legacy)。
+//   endpointToAction / endpointToReadAction 现从该模块 import(见文件顶部)。
 function getDeclaredActions(apiKey) {
     const row = db.prepare(`SELECT declared_scope FROM agent_declarations WHERE api_key = ? AND revoked_at IS NULL`).get(apiKey);
     if (!row)
@@ -7605,7 +7516,7 @@ registerOrdersReadRoutes(app, { db, auth, getOrderStatus, getOrderChain, verifyO
 // 注意：settleOrder 是函数声明（hoisted）但绑了 db 闭包，无需注入 db
 registerOrdersActionRoutes(app, {
     db, auth, isTrustedRole, generateId, transition, notifyTransition,
-    settleOrder, detectFraud, createDispute, checkTimeouts, recordViolationReputation,
+    settleOrder, settleFault, detectFraud, createDispute, checkTimeouts, recordViolationReputation,
     broadcastSystemEvent,
 });
 // #1013 Phase 85: POST /api/orders 巨型事务已迁出
@@ -10287,8 +10198,8 @@ db.exec(`
     const existing = db.prepare("SELECT version FROM rewards_consent_texts WHERE version = '1.0'").get();
     if (existing)
         return;
-    const textZh = 'WebAZ 共建身份(rewards opt-in)v1.0 — 由 RFC-002 §3.3 / §3.10 定义。本同意涉及经济关系登记 + Passkey 真人签名 + 三级佣金 + 二元配对树参与。详见 RFC-002 全文。本流程与购物无关,可随时退出,不影响订单。';
-    const textEn = 'WebAZ Builder Identity (rewards opt-in) v1.0 — defined by RFC-002 §3.3 / §3.10. This consent records an economic relationship with Passkey-signed proof of personhood + participation in 3-tier commission + binary PV matching tree. See full RFC-002. This flow is not part of shopping; you may leave anytime without affecting orders.';
+    const textZh = 'WebAZ 共建身份(rewards opt-in)v1.0 — 由 RFC-002 §3.3 / §3.10 定义。本同意涉及经济关系登记 + Passkey 真人签名 + 三级佣金 + 积分配对参与。详见 RFC-002 全文。本流程与购物无关,可随时退出,不影响订单。';
+    const textEn = 'WebAZ Builder Identity (rewards opt-in) v1.0 — defined by RFC-002 §3.3 / §3.10. This consent records an economic relationship with Passkey-signed proof of personhood + participation in 3-tier commission + points-matching. See full RFC-002. This flow is not part of shopping; you may leave anytime without affecting orders.';
     const hash = createHash('sha256').update(textZh + '\n---\n' + textEn).digest('hex');
     db.prepare(`INSERT INTO rewards_consent_texts (version, hash, change_class, effective_at, text_zh, text_en, changelog)
               VALUES (?, ?, 'major', ?, ?, ?, ?)`)

package/dist/pwa/verifiability-index.js

@@ -0,0 +1,63 @@
+/**
+ * RFC-011 §⑤ 可验证索引 —— 一份"什么可验 + 怎么验"的总表(护照/锚/AP2/订单链散在四处,这里统一)。
+ * 诚实分级(不可过度声明):
+ *   - 护照 / 外部锚:公开可验(任何第三方离线 ecrecover / 验签),强。
+ *   - AP2 Mandate:签名输出,可验。
+ *   - 订单事件链:HMAC 是 actor 私钥 → 第三方【无法】验签;可验的是【哈希链连续性】(防篡改),且 party-gated。
+ * 只【链接 + 说明】how-to,不嵌密钥(密钥 live 发布在 did.json / protocol-status issuers),doc=code 不漂移。
+ */
+import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
+const BASE = 'https://webaz.xyz';
+export function buildVerifiabilityIndex() {
+    return {
+        contract_version: CONTRACT_VERSION,
+        software_version: SOFTWARE_VERSION,
+        note: 'RFC-011 §⑤. Each artifact lists what it proves, the scheme, how to verify, and its verifiability LEVEL — do not over-trust beyond the stated level. Issuer keys are published live (not embedded here): /.well-known/did.json + /.well-known/webaz-protocol.json#issuers.',
+        levels: {
+            public_signature: 'any third party verifies offline (ecrecover / sig-check) without calling WebAZ',
+            public_endpoint: 'verifiable via a public WebAZ endpoint (no auth)',
+            integrity_chain: 'tamper-evidence via a hash-chain (verify continuity); NOT a third-party-verifiable signature',
+            party_gated: 'full data only to order parties; others get integrity, not contents',
+        },
+        artifacts: [
+            {
+                artifact: 'agent_passport',
+                proves: 'an agent\'s custodian fingerprint + risk/engagement/behavior, signed by the WebAZ issuer key',
+                scheme: 'eip191 (EIP-191 personal_sign)',
+                level: 'public_signature',
+                offline: true,
+                how_to_verify: 'GET /api/me/agents/:apiKeyPrefix/passport → ecrecover(passport.canonical, passport.signature) == issuer address from /.well-known/did.json (CAIP-10) / /.well-known/webaz-protocol.json#issuers; check active_since/revoked_at window.',
+                endpoint: `${BASE}/api/me/agents/:apiKeyPrefix/passport`,
+                keys: `${BASE}/.well-known/did.json`,
+            },
+            {
+                artifact: 'external_anchor',
+                proves: 'a real-world item\'s ownership/authenticity anchor + independent verifier attestations',
+                scheme: 'signature (server-verifiable)',
+                level: 'public_endpoint',
+                offline: false,
+                how_to_verify: `GET ${BASE}/api/external-anchors/:id/verify-sig (public); cross-check verifier attestations via /api/external-anchors/:id.`,
+                endpoint: `${BASE}/api/external-anchors/:id/verify-sig`,
+            },
+            {
+                artifact: 'ap2_mandate',
+                proves: 'a buyer\'s signed Intent/Cart/Payment Mandate (AP2) emitted alongside the webaz price/order format',
+                scheme: 'AP2 signed mandate',
+                level: 'public_signature',
+                offline: true,
+                how_to_verify: 'verify the AP2 mandate signature per the AP2 spec; emitted by webaz_verify_price + webaz_place_order (dual-output).',
+                endpoint: 'returned inline by verify_price / place_order',
+            },
+            {
+                artifact: 'order_event_chain',
+                proves: 'the order/dispute transition history is append-only + tamper-evident (each event hash chains to the previous)',
+                scheme: 'sha256 hash-chain (event_hash / prev_event_hash). NOTE: the per-event `signature` is an HMAC with the actor\'s api_key — NOT third-party verifiable; the verifiable property is the HASH-CHAIN continuity.',
+                level: 'integrity_chain',
+                offline: true,
+                party_gated: true,
+                how_to_verify: `For an order you are party to: GET ${BASE}/api/orders/:id/chain (returns chain + verification). Or stream events via ${BASE}/api/agent/events (§⑥): check each event\'s prev_event_hash == the previous event\'s event_hash. Continuity proves no insert/delete/reorder.`,
+                endpoint: `${BASE}/api/orders/:id/chain`,
+            },
+        ],
+    };
+}

package/dist/version.js

@@ -0,0 +1,32 @@
+/**
+ * Single source of truth for WebAZ version axes — RFC-011 §④ (version hygiene).
+ *
+ * TWO DISTINCT AXES. Do not conflate them — conflating is exactly the dirt this file kills
+ * (the old hardcoded MCP `SERVER_VERSION='0.1.8'` + Server handshake `version:'0.1.0'` drifted
+ *  away from the real package version 0.1.19; this makes that structurally impossible).
+ *
+ * 1. SOFTWARE_VERSION — npm / release semver of THIS codebase (MCP client+server + PWA).
+ *    Read from package.json at runtime so it can NEVER drift. Bumps on every release.
+ *    Resolves from both dev (tsx src/version.ts → ../package.json) and prod/published
+ *    (node dist/version.js → ../package.json), since package.json sits at the package root
+ *    and is always included in the npm tarball.
+ *
+ * 2. CONTRACT_VERSION — the agent-native INTEGRATION CONTRACT version (manifest `schema_version`).
+ *    A deliberate integer that integrators' agents key off. Bump ONLY on a *breaking* change to
+ *    the data contract they read (entity shape / boundary / verifiable-field semantics).
+ *    INDEPENDENT of software releases — a patch/feature release does NOT bump it; a breaking
+ *    contract change DOES, even within the same software version. Governs RFC-011's contract.
+ *
+ * Both are surfaced to integrators in /.well-known/webaz-protocol.json so an agent can read
+ * "contract vN running software x.y.z" and decide compatibility.
+ */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+/** npm/release semver — single source = package.json. Never hardcode a copy of this. */
+export const SOFTWARE_VERSION = pkg.version;
+/** Integration-contract version. Bump on ANY integrator-observable contract-surface change
+ *  (capability matrix §② / entity dictionary §①); the CONTRACT_CHANGES `kind` classifies whether
+ *  it is breaking. Additive changes (kind:'added') are safe for agents to ignore. Guarded by
+ *  tests/test-contract-fingerprint.ts + docs/CONTRACT-LOCK.json. */
+export const CONTRACT_VERSION = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "[PRE-LAUNCH] Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools. ⚠️ Repository currently private until W8 public launch — GitHub links may return 404. See https://webaz.xyz for status.",
   "main": "dist/mcp.js",
   "bin": {
@@ -20,6 +20,7 @@
     "enforcement": "tsx src/cron-enforcement.ts",
     "pwa": "tsx src/pwa/server.ts",
     "schema:verify": "tsx scripts/schema-verify.ts",
+    "contract:verify": "tsx tests/test-contract-fingerprint.ts",
     "license:check": "tsx scripts/license-invariant-check.ts",
     "meta-rules:check": "tsx scripts/meta-rules-invariant-check.ts",
     "params:check": "tsx scripts/meta-rule-locked-params-check.ts"