@seasonkoh/webaz 0.1.18 → 0.1.20

package/dist/layer2-business/L2-8-feedback/build-feedback-engine.js

@@ -2,6 +2,8 @@ import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
 // RFC-006 不变量 1:建设贡献记入【独立】build_reputation 池,不再写交易 reputation_scores
 //（旧:recordRepEvent('feedback_accepted') 会污染 verifier/arbitrator 准入,已隔离)。
 import { creditBuildReputation, BUILD_POINTS } from '../L2-9-contribution/build-reputation-engine.js';
+// RFC-006 桥(use→build 漏斗补全):采纳的 proposal → 自动建 build_task + 邀请提案人来认领。
+import { createBuildTask } from '../L2-9-contribution/build-tasks-engine.js';
 export const FB_TYPES = new Set(['ux_issue', 'bug', 'proposal']);
 export const FB_SEVERITY = new Set(['low', 'annoying', 'blocking']);
 export const FB_STATUS = new Set(['received', 'triaged', 'in_progress', 'resolved', 'declined', 'duplicate']);
@@ -38,6 +40,11 @@ export function initBuildFeedbackSchema(db) {
         'ALTER TABLE build_feedback ADD COLUMN ai_summary TEXT', // 一句话摘要(给 maintainer 扫)
         'ALTER TABLE build_feedback ADD COLUMN ai_models TEXT', // 参与的模型 + 是否一致
         'ALTER TABLE build_feedback ADD COLUMN ai_triaged_at TEXT',
+        // RFC-006 桥:采纳的 proposal 被 promote 成 build_task 时,记其 task id(use→build 漏斗:反馈→协调)
+        'ALTER TABLE build_feedback ADD COLUMN promoted_task_id TEXT',
+        // RFC-004 体验补:受理时本可记功、但提交者【无 Passkey 锚点】而跳过 → 标记为待补发,
+        //   绑定 Passkey 后由 grantPendingAnchorCredits 追溯发放(把"静默不记分"变成"绑 Passkey 领取")。
+        'ALTER TABLE build_feedback ADD COLUMN credit_pending_anchor INTEGER DEFAULT 0',
     ]) {
         try {
             db.exec(stmt);
@@ -133,10 +140,33 @@ function parse(row) {
     return { ...rest, scene };
 }
 export function listMyBuildFeedback(db, userId) {
-    const rows = db.prepare(`SELECT id, type, area, severity, subject, body, status, dedup_of, resolution, credited_points, created_at, updated_at
+    const rows = db.prepare(`SELECT id, type, area, severity, subject, body, status, dedup_of, resolution, credited_points, credit_pending_anchor, promoted_task_id, created_at, updated_at
      FROM build_feedback WHERE user_id = ? ORDER BY created_at DESC LIMIT 100`).all(userId);
     return rows;
 }
+/**
+ * RFC-004 体验补:提交者【事后】绑定 Passkey 时,追溯补发此前"已受理但因无锚点跳过记功"的贡献信誉。
+ * 原则自洽:受理已由 maintainer 把关(分是挣得的),Passkey 只是解锁"奖励锚真人"——故补发无 gaming 风险。
+ * 幂等:creditBuildReputation 按 (source, ref_id) 去重;且只扫 credit_pending_anchor=1 的行。绑定流程调用,advisory 永不阻塞。
+ */
+export function grantPendingAnchorCredits(db, userId) {
+    const hasAnchor = ((db.prepare('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?')
+        .get(userId)?.n) || 0) > 0;
+    if (!hasAnchor)
+        return { granted: 0, total_points: 0 };
+    const rows = db.prepare(`SELECT id FROM build_feedback WHERE user_id = ? AND credit_pending_anchor = 1`).all(userId);
+    let granted = 0, total = 0;
+    for (const r of rows) {
+        const res = creditBuildReputation(db, userId, 'feedback_accepted', BUILD_POINTS.feedback_accepted, r.id, `feedback ${r.id} accepted (anchor backfill)`);
+        db.prepare(`UPDATE build_feedback SET credited_points = ?, credit_pending_anchor = 0, updated_at = datetime('now') WHERE id = ?`)
+            .run(BUILD_POINTS.feedback_accepted, r.id);
+        if (!res.already) {
+            granted++;
+            total += BUILD_POINTS.feedback_accepted;
+        }
+    }
+    return { granted, total_points: total };
+}
 export function getBuildFeedback(db, id, userId, isAdmin) {
     const row = db.prepare('SELECT * FROM build_feedback WHERE id = ?').get(id);
     if (!row)
@@ -163,23 +193,52 @@ export function adminUpdateBuildFeedback(db, u) {
     // 无 Passkey 的报告者(报问题=用)可受理致谢,但无锚点不记分。
     let credited = Number(row.credited_points) || 0;
     let credit_skipped_no_anchor = false;
+    let pendingFlag = null; // null = 不改 credit_pending_anchor;1 = 待补发;0 = 已发/清除
     if (u.credit && newStatus === 'resolved' && credited === 0) {
         const hasAnchor = ((db.prepare('SELECT COUNT(*) AS n FROM webauthn_credentials WHERE user_id = ?')
             .get(row.user_id)?.n) || 0) > 0;
         if (hasAnchor) {
             creditBuildReputation(db, row.user_id, 'feedback_accepted', BUILD_POINTS.feedback_accepted, u.id, `feedback ${u.id} accepted`);
             credited = BUILD_POINTS.feedback_accepted;
+            pendingFlag = 0;
         }
         else {
-            credit_skipped_no_anchor = true; // 受理但不记分(提交者无 Passkey 锚点)
+            credit_skipped_no_anchor = true; // 受理但不记分(提交者无 Passkey 锚点)→ 标记待补发,绑 Passkey 后发放
+            pendingFlag = 1;
         }
     }
     db.prepare(`UPDATE build_feedback SET status = ?, resolution = COALESCE(?, resolution),
-      rfc_draft = COALESCE(?, rfc_draft), credited_points = ?, handled_by = ?, updated_at = datetime('now')
-    WHERE id = ?`).run(newStatus, u.resolution ?? null, u.rfcDraft ?? null, credited, u.adminId, u.id);
+      rfc_draft = COALESCE(?, rfc_draft), credited_points = ?, credit_pending_anchor = COALESCE(?, credit_pending_anchor),
+      handled_by = ?, updated_at = datetime('now')
+    WHERE id = ?`).run(newStatus, u.resolution ?? null, u.rfcDraft ?? null, credited, pendingFlag, u.adminId, u.id);
     if (newStatus !== fromStatus)
         logEvent(db, u.id, u.adminId, fromStatus, newStatus, u.resolution ?? null);
-    return { ok: true, credited, ...(credit_skipped_no_anchor ? { credit_skipped_no_anchor: true } : {}) };
+    // RFC-006 桥(use→build 漏斗补全):maintainer 采纳提案时可 promote 成可认领的 build_task,
+    //   并【邀请提案人】来认领——把"反馈被采纳"接到"来一起建设",补上漏斗最大断点。
+    //   幂等:已 promote 过(promoted_task_id 非空)不重复建。
+    let promoted_task_id;
+    const already = row.promoted_task_id || null;
+    if (u.promoteToTask && !already && row.type === 'proposal') {
+        const title = (row.subject || row.body || 'contributor proposal').slice(0, 200);
+        const created = createBuildTask(db, {
+            creatorId: u.adminId,
+            title,
+            area: row.area || undefined,
+            description: `From accepted proposal ${u.id} (by ${row.user_id}).\n\n${row.body || ''}`.slice(0, 4000),
+            rfcRef: row.rfc_draft || undefined,
+        });
+        if ('id' in created) {
+            promoted_task_id = created.id;
+            db.prepare('UPDATE build_feedback SET promoted_task_id = ? WHERE id = ?').run(promoted_task_id, u.id);
+            // 邀请提案人:通知 + 反馈闭环里会显示 promoted_task_id
+            try {
+                db.prepare(`INSERT INTO notifications (id, user_id, type, title, body) VALUES (?,?,?,?,?)`).run(generateId('ntf'), row.user_id, 'build_invite', '你的提案被采纳了 — 来一起建设?', `提案「${title}」已被采纳并建成可认领任务 ${promoted_task_id}。在「我的共建」用 webaz_contribute 认领即可参与实现。`);
+            }
+            catch { /* notifications 可选,不阻断 */ }
+            logEvent(db, u.id, u.adminId, newStatus, newStatus, `promoted → task ${promoted_task_id}`);
+        }
+    }
+    return { ok: true, credited, ...(credit_skipped_no_anchor ? { credit_skipped_no_anchor: true } : {}), ...(promoted_task_id ? { promoted_task_id } : {}) };
 }
 // ─── RFC-005 Phase 2:AI triage(advisory)─────────────────────────
 // 给"内部反馈"打标,不碰代码、不 resolve、不记功(那是人类的)。无 key 也能跑(只做确定性去重 + 置 triaged)。

package/dist/layer2-business/L2-9-contribution/build-reputation-engine.js

@@ -57,6 +57,10 @@ export function creditBuildReputation(db, userId, source, points, refId, note) {
     }
     return { credited: points };
 }
+// RFC-006 stage 4(恶意管理)= 复用现有问责中间件,**无需新代码**:
+// build_tasks 是 api_key 写端点,被 strike 至 suspend_7d/permanent 的贡献者已被 isApiKeyBlocked
+// (server.ts)挡在所有写之外,包括建设。strike/blocklist/outlier 对建设贡献自动生效。
+// 看板这里只【展示】当事人的活跃 strike + 申诉入口(透明先于强制);真人申诉走现成 strikes/:id/appeal。
 // 贡献者【自查】档案 —— KPI + 等级 + 来源拆分 + provenance + 限制/惩罚 + 申诉入口。
 // 不变量 3:仅本人可调(路由层 auth);不做公开榜。
 export function getBuildProfile(db, userId) {

package/dist/pwa/contract-fingerprint.js

@@ -0,0 +1,46 @@
+/**
+ * RFC-011 §④ 契约变更体系 —— 让 feed 诚实(防 CHANGELOG-rot 那个失败模式)。
+ *
+ * 思路:给每个【契约面】(②能力矩阵 / ①实体字典)算确定性指纹(canonical + sha256),
+ *   排除 software_version 等易变位 —— 只盖集成方依赖的契约内容。committed 基线 docs/CONTRACT-LOCK.json
+ *   按 contract_version 锁;tests/test-contract-fingerprint.ts 守卫:指纹变了但 CONTRACT_VERSION 没 bump
+ *   → FAIL,逼"bump + 写 CONTRACT_CHANGES 条目 + 更基线"。静默改契约不可 merge(= schema:verify 模式)。
+ *
+ * 版本模型:CONTRACT_VERSION = 契约内容修订号,任何 integrator-observable 变更都 bump;
+ *   变更条目的 kind(added|changed|deprecated|removed)由人分类是否破坏性(additive agent 可忽略)。
+ */
+import { createHash } from 'node:crypto';
+import { capabilityMatrix } from './endpoint-actions.js';
+import { buildEntityDictionary } from './entity-dictionary.js';
+import { canonicalSerialize } from '../layer0-foundation/L0-2-state-machine/order-chain.js';
+import { CONTRACT_VERSION } from '../version.js';
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+// 契约投影 —— 只取集成方依赖的契约内容,【排除】software_version / 易变 roadmap(todo)。
+function contractProjection() {
+    const cap = capabilityMatrix();
+    const ent = buildEntityDictionary();
+    return {
+        capability: { model: cap.model, write_actions: cap.write_actions, safe_write_unscoped: cap.safe_write_unscoped, read_scopes: cap.read_scopes, notes: cap.notes },
+        entity: { note: ent.note, entities: ent.entities }, // 注:不含 ent.software_version / ent.todo
+    };
+}
+export function contractFingerprints() {
+    const p = contractProjection();
+    const capability = sha256(canonicalSerialize(p.capability));
+    const entity = sha256(canonicalSerialize(p.entity));
+    return { contract_version: CONTRACT_VERSION, capability, entity, combined: sha256(`${capability}|${entity}`) };
+}
+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.' },
+];
+export function buildChangeFeed() {
+    return {
+        current_contract_version: CONTRACT_VERSION,
+        fingerprints: contractFingerprints(),
+        deprecation_policy: 'Sunset-bound surfaces carry RFC 8594 Deprecation + Sunset headers; window ≥ 1 contract_version. Any integrator-observable contract change bumps contract_version and appends a change entry (kind: added|changed|deprecated|removed). A fingerprint CI guard makes a silent change un-mergeable.',
+        deprecations: [],
+        changes: CONTRACT_CHANGES,
+        note: 'Poll with your last-seen contract_version and apply entries with a higher contract_version. The fingerprints let you detect drift without diffing the whole contract: if combined != your cached value, re-read /.well-known/webaz-{capabilities,entities}.json.',
+    };
+}

package/dist/pwa/economic-participation.js

@@ -0,0 +1,122 @@
+/**
+ * RFC-011 §⑧ 经济参与索引 —— 外部 actor 进入协议【价值流】的统一契约面。
+ *
+ * 价值参与 = liability_tiers 里最高的 `value_participant` 层:不只是读(①)/写(②),
+ * 而是【赚费 + 押抵押 + 承担守恒的连带责任】。本表把【已存在 + 已 enforce】的角色串起来。
+ *
+ * doc=code 纪律(同 ④⑤⑥):
+ *   - 费率/门槛【请求时实时从 protocol_params 读】(getParam 注入),永不和 enforced 经济漂移 —— 反 #1094 装饰化。
+ *   - 守恒是硬不变量:所有罚没【再分配,绝不增发】(settleFault)。
+ *   - 诚实 status:已上线角色标 live;通用第三方承保方(无真实需求)标 scaffolded → 自有 RFC + enters-core 门控,不过早造接口。
+ *
+ * 公平三原则锚([[project_fairness_principle]]):公开透明 / 谁责任谁承担 / 无责方零成本。
+ */
+import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
+const GH = 'https://github.com/seasonsagents-art/webaz/blob/main';
+const BASE = 'https://webaz.xyz';
+export function buildEconomicParticipation(getParam) {
+    const num = (k, f) => getParam(k, f);
+    return {
+        contract_version: CONTRACT_VERSION,
+        software_version: SOFTWARE_VERSION,
+        note: 'RFC-011 §⑧. The roles by which an external actor enters the protocol VALUE flow (earns fees / posts collateral / bears conserved liability) — the highest liability tier (value_participant). Rates & thresholds are read LIVE from protocol_params at request time (doc=code: this index can never drift from the enforced economics). Honesty: roles marked status=live are enforced today; status=scaffolded means the hook exists but generic third-party onboarding awaits its own RFC + real demand (enters-core test).',
+        principles: {
+            fairness: ['public & transparent', 'liability follows the responsible party', 'zero cost to the faultless party'],
+            conservation: 'Every settlement conserves value: a forfeit F is REDISTRIBUTED (protocol ≤ its fee, fund_base excluded / buyer up to 50% / promoters capped at original commission / residual → commission_reserve) — never minted. See engine.settleFault.',
+            bootstrap_no_forfeit: 'RFC-008: an order with stake_backing=0 (bootstrap / require_seller_stake=0) incurs ZERO forfeit and never touches the participant\'s free balance. Real forfeit applies only to staked orders.',
+        },
+        enter_value_flow: 'A value participant is in the accountability net via api_key→passport AND collateral/reputation-bound. Highest liability tier. See /.well-known/webaz-integration.json#liability_tiers.value_participant.',
+        roles: [
+            {
+                role: 'seller_shop',
+                enters_as: 'lists products + fulfills orders',
+                earns: { source: 'sale proceeds minus protocol fee', protocol_fee_rate: num('protocol_fee_rate_shop', 0.02), fee_hard_cap: 0.02, fee_note: 'RFC-008 hard cap 2%, can only decrease; pre-launch may be waived lower.' },
+                collateral: { required: num('require_seller_stake', 0) === 1, param: 'require_seller_stake', model: 'RFC-008 stake_backing per order; bootstrap (=0) → zero forfeit.' },
+                liability: { fault_states: ['fault_seller'], penalty_rate: num('fault_penalty_rate', 0.30), penalty_note: 'decoupled from stake rate; staked orders forfeit from stake then free balance; bootstrap orders exempt.', settlement: 'engine.settleFault (conserved)' },
+                gate: 'api_key (authenticated_write)',
+                status: 'live',
+                enforced_by: 'routes/orders-create.ts + layer0 engine.settleFault',
+            },
+            {
+                role: 'seller_secondhand',
+                enters_as: 'lists used items + fulfills',
+                earns: { source: 'sale proceeds minus protocol fee', protocol_fee_rate: num('protocol_fee_rate_secondhand', 0.01), fee_hard_cap: 0.02, fee_note: 'RFC-008 hard cap 2%, can only decrease.' },
+                collateral: { required: num('require_seller_stake', 0) === 1, param: 'require_seller_stake', model: 'same RFC-008 stake model as seller_shop.' },
+                liability: { fault_states: ['fault_seller'], penalty_rate: num('fault_penalty_rate', 0.30), settlement: 'engine.settleFault (conserved)' },
+                gate: 'api_key (authenticated_write)',
+                status: 'live',
+                enforced_by: 'routes/orders-create.ts + engine.settleFault',
+            },
+            {
+                role: 'promoter',
+                enters_as: 'shares a product link; earns commission on attributed sales',
+                earns: { source: 'commission on attributed order', default_commission_rate: num('default_commission_rate', 0.05), rate_note: 'per-product, seller-set; default shown here.' },
+                collateral: { required: false, model: 'none; promoter takes no fulfillment liability.' },
+                liability: { fault_states: [], note: 'on a fault settlement a promoter\'s payout is clawed back but capped at the original commission (conservation) — never negative.' },
+                gate: 'api_key (authenticated_write)',
+                status: 'live',
+                enforced_by: 'commission attribution + engine.settleFault forfeit distribution',
+            },
+            {
+                role: 'logistics',
+                enters_as: 'carries the order; reports pickup/transit/delivery evidence',
+                earns: { source: 'order-specific logistics fee (negotiated off-protocol / per-order, NOT a global protocol param)', protocol_param: null },
+                collateral: { required: false, optional_hook: 'insurance_cap', model: 'a carrier may set insurance_cap on an order; loss above the cap is covered by the protocol fund (buyer still fully compensated).' },
+                liability: { fault_states: ['fault_logistics'], settlement: 'engine.settleFault (conserved); carrier bears loss up to insurance_cap.' },
+                gate: 'api_key (authenticated_write) + evidence (gps/photo) on transitions',
+                status: 'live',
+                enforced_by: 'L0-2 state machine transitions + L3-1 dispute-engine (insurance_cap)',
+            },
+            {
+                role: 'anchor_verifier',
+                enters_as: 'independently verifies a seller\'s external-anchor (real-world ownership/authenticity) claim by voting',
+                earns: { source: 'verification_fee the seller attached to the anchor, split evenly among correct (content_matches=1) voters on community upgrade', recommended_fee: 2.0, fee_note: 'seller-set per anchor (may be 0 = community verification off); not a global param.' },
+                collateral: { required: true, field: 'verifier_whitelist.stake_amount', model: 'staked to join the verifier whitelist.' },
+                liability: { fault_states: ['verifier_error'], penalty: 'on an error, 50% of stake_amount forfeited from staked balance.', settlement: 'anchor-engine + verifier_whitelist' },
+                gate: `reputation ≥ ${num('governance_onboarding.verifier_min_reputation', 90)} (param) + live WebAuthn per vote (iron-rule)`,
+                status: 'live',
+                enforced_by: 'L1-2 anchor-engine (fee split) + verifier_whitelist (stake/forfeit)',
+            },
+            {
+                role: 'arbitrator',
+                enters_as: 'adjudicates disputes (objective-claimed non-acceptance, fault contests)',
+                earns: { source: 'a per-dispute arbitration fee (today: 50% of orderAmount×1%, paid by the loser). Compensated, NOT fee-maximizing — pay must stay independent of the ruling; see RFC-013 (decouples pay from ruling direction + fixes the latent "rule against who can pay" bias).', rfc: `${GH}/docs/rfcs/RFC-013-arbitrator-compensation-independence.md` },
+                collateral: { required: false, model: 'reputation-bound rather than stake-bound; mis-adjudication damages reputation.' },
+                liability: { note: 'accountable via reputation + audit log; iron-rule human presence required.' },
+                gate: `reputation ≥ ${num('governance_onboarding.arbitrator_min_reputation', 95)} (param) + live WebAuthn per ruling (iron-rule)`,
+                status: 'live',
+                enforced_by: 'L3-1 dispute-engine + governance onboarding gates',
+            },
+            {
+                role: 'skill_author',
+                enters_as: 'publishes a knowledge skill to the skill market; earns on sales',
+                earns: { source: 'sale price minus protocol fee', skill_fee_rate: num('skill_fee_rate', 0.05), payout_note: 'author nets price × (1 − skill_fee_rate). Independent revenue stream — NOT routed into commission/PV.' },
+                collateral: { required: false },
+                liability: { note: 'subject to skill-market review + meta-rules; refunds per market policy.' },
+                gate: 'api_key (authenticated_write) + skill-market review',
+                status: 'live',
+                enforced_by: 'skill-market engine + admin review',
+            },
+            {
+                role: 'insurer',
+                enters_as: '(generic third-party underwriter) prices & carries order risk for a premium',
+                earns: { source: 'order insurance premium', order_insurance_rate: num('order_insurance_rate', 0.01), today: 'buyer opt-in premium accrues at the protocol rate; there is NOT yet a generic external-underwriter market.' },
+                collateral: { required: true, model: 'an external underwriter would post collateral backing its book — to be defined.' },
+                liability: { note: 'would pay out covered losses; bound by collateral.' },
+                gate: 'TBD (own RFC)',
+                status: 'scaffolded',
+                spec: `${GH}/docs/rfcs/RFC-012-external-risk-underwriter.md`,
+                why_not_live: 'No real underwriters yet. Per the enters-core test (≥N independent integrators × cross-party trust × not reconstructable), generic underwriter onboarding is specified in RFC-012 (collateralized risk-cover bound to RFC-008; NOT licensed insurance) and gated on real demand — we do not pre-build the interface.',
+                enforced_by: 'order_insurance_rate premium (live) + insurance_cap fund backstop (live); generic underwriter onboarding: to-build',
+            },
+        ],
+        human_gates: 'arbitrate / verifier-vote / large withdraw require a live WebAuthn ceremony regardless of scope (iron-rule).',
+        references: {
+            economic_model: `${BASE}/docs/ECONOMIC-MODEL.md`, // 协议自服务(公开经济模型)
+            rfc_008: `${GH}/docs/rfcs/RFC-008-merchant-cost-collateral.md`,
+            rfc_011: `${GH}/docs/rfcs/RFC-011-agent-native-integration-contract.md`,
+            rfc_012_underwriter: `${GH}/docs/rfcs/RFC-012-external-risk-underwriter.md`,
+            liability_tiers: 'https://webaz.xyz/.well-known/webaz-integration.json',
+        },
+    };
+}

package/dist/pwa/endpoint-actions.js

@@ -0,0 +1,112 @@
+/**
+ * Endpoint → action-scope classifier — the WRITE-boundary spine (元规则 #3 + #1115 default-deny).
+ * RFC-011 §② (capability matrix): the SAME declarative rules that ENFORCE the boundary at runtime
+ * are also SERIALIZED (capabilityMatrix) and published live, so an integrator's agent reads exactly
+ * what the protocol enforces — doc=code, zero drift. Extracted from server.ts unchanged in behaviour
+ * (locked by tests/test-endpoint-actions.ts, which diffs this against the legacy if-chain).
+ *
+ * Model: GET reads are open (except the sensitive cross-user read scopes below). Every WRITE either
+ * maps to a named action-scope token (agent must declare that scope, or hold a Passkey, or declare '*'),
+ * or is on the SAFE list (write allowed without a declared scope — bootstrap/auth/low-value self-state),
+ * or falls through to the generic 'write' token (default-deny: new sensitive writes are gated by default).
+ */
+import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
+/** Ordered write-action rules. Order matters (first match wins). Mirrors the legacy if-chain exactly. */
+export const WRITE_RULES = [
+    { method: 'POST', exact: '/api/orders', action: 'place_order' },
+    { method: 'POST_PUT', re: /^\/api\/products(\/[^/]+)?$/, action: 'list_product' },
+    { method: 'POST', re: /^\/api\/orders\/[^/]+\/(accept|ship|deliver|pickup|transit)/, action: 'fulfill' },
+    { method: 'POST', re: /^\/api\/orders\/[^/]+\/confirm/, action: 'confirm_order' },
+    { method: 'POST', re: /^\/api\/claim-tasks\/[^/]+\/vote/, action: 'vote' },
+    { method: 'POST', re: /^\/api\/disputes\/[^/]+\/arbitrate/, action: 'arbitrate' },
+    { method: 'POST', re: /^\/api\/disputes\/[^/]+\/respond/, action: 'dispute_respond' },
+    { method: 'POST', re: /^\/api\/charity\/fund\/donate/, action: 'donate' },
+    { method: 'POST', re: /^\/api\/(wishes|charity)/, action: 'charity' },
+    { method: 'POST', re: /^\/api\/shareables/, action: 'share' },
+    { method: 'POST', re: /^\/api\/conversations/, action: 'chat' },
+    { method: 'POST', exact: '/api/skills', action: 'list_skill' },
+    { method: 'POST', re: /^\/api\/rfqs/, action: 'rfq' },
+    { method: 'POST', re: /^\/api\/auctions\/[^/]+\/bid/, action: 'bid' },
+    // #1115 P0:花钱/价值写纳入问责门(与 place_order 同档)
+    { 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' },
+    // #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' },
+    // #1115 P2:钱包写统一 'wallet'(withdraw 另在 handler 强制 Passkey 铁律)
+    { method: 'WRITE', re: /^\/api\/wallet\//, action: 'wallet' },
+    // #1115 P2:profile PII/身份/接管向量子集 'set_profile'(其余 profile 自助写在 SAFE)
+    { method: 'WRITE', re: /^\/api\/profile\/(bind-email|confirm-email|change-handle|change-name|set-location|clear-location)$/, action: 'set_profile' },
+];
+/** SAFE writes — allowed without a declared scope (bootstrap/auth/self-bound-gate/low-value self-state). */
+export const SAFE_WRITE = [
+    /^\/api\/(login|register)$/, /^\/api\/recover-key/, /^\/api\/webauthn\//,
+    /^\/api\/me\/agents\//,
+    /^\/api\/profile\/(switch-role|add-role|region|placement-pref|bind-placement|feed-visible|verify-password|set-password|remove-password)$/,
+    /^\/api\/build-feedback/, /^\/api\/build-tasks/, /^\/api\/admin\//,
+    /^\/api\/(public-ideas|error-report|mcp-telemetry|email-subscriptions|search-by-link|feedback)(\/|$)/,
+    /^\/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\//,
+];
+function methodMatches(m, method) {
+    if (m === 'POST')
+        return method === 'POST';
+    if (m === 'POST_PUT')
+        return method === 'POST' || method === 'PUT';
+    return method !== 'GET'; // WRITE
+}
+/** Write-boundary classifier. Returns a named action-scope token, or 'write' (generic), or null (open). */
+export function endpointToAction(method, path) {
+    if (method === 'GET')
+        return null;
+    for (const r of WRITE_RULES) {
+        if (!methodMatches(r.method, method))
+            continue;
+        if (r.exact !== undefined ? path === r.exact : r.re.test(path))
+            return r.action;
+    }
+    if (SAFE_WRITE.some(re => re.test(path)))
+        return null;
+    return 'write'; // 默认拒绝:其余写需问责
+}
+/** Sensitive cross-user READ scopes (Phase 3b B1) — only constrains *declared* agents; humans/'*'/undeclared exempt. */
+export const READ_RULES = [
+    { re: /^\/api\/nearby/, scope: 'search' }, // 雷达扫描(地理聚合)
+    { re: /^\/api\/search/, scope: 'search' }, // 模糊搜索深翻页
+    { re: /^\/api\/users\/[^/]+\//, scope: 'profile' }, // 他人主页/信誉/内容流(枚举剽窃向)
+];
+export function endpointToReadAction(path) {
+    for (const r of READ_RULES)
+        if (r.re.test(path))
+            return r.scope;
+    return null;
+}
+/** Serialize the live boundary as the agent-readable capability matrix (RFC-011 §②). doc=code. */
+export function capabilityMatrix() {
+    return {
+        contract_version: CONTRACT_VERSION,
+        software_version: SOFTWARE_VERSION,
+        model: 'default-deny writes. GET reads are open except the sensitive cross-user read scopes. Every write either maps to a named action-scope token (the agent must declare that scope on its api_key, OR hold a Passkey, OR declare "*"), or is SAFE (write allowed unscoped), or falls through to the generic "write" token.',
+        write_actions: WRITE_RULES.map(r => ({
+            action: r.action,
+            method: r.method === 'POST' ? 'POST' : r.method === 'POST_PUT' ? 'POST|PUT' : 'POST|PUT|PATCH|DELETE',
+            match: r.exact !== undefined ? `=${r.exact}` : r.re.source,
+        })),
+        safe_write_unscoped: SAFE_WRITE.map(re => re.source),
+        read_scopes: READ_RULES.map(r => ({ scope: r.scope, match: r.re.source })),
+        notes: {
+            passkey_exempt: 'A Passkey-bound human is exempt from scope-declaration (但仍受铁律真人门约束).',
+            iron_rule: 'arbitrate / vote / agent_revoke / delete_passkey / large withdraw require a live WebAuthn ceremony regardless of declared scope (CHARTER §4 iron-rule).',
+            undeclared: 'An agent that has NOT declared any actions and has no Passkey is denied any named/ generic write (AGENT_SCOPE_UNDECLARED).',
+        },
+    };
+}

package/dist/pwa/entity-dictionary.js

@@ -0,0 +1,125 @@
+/**
+ * RFC-011 §① 实体字典 —— agent 可读的"数据是什么 + 状态机 + 哪些可验证"。
+ *   - 状态机:从 transitions.ts 生成(doc=code,零漂移)。
+ *   - 字段含义:authored(schema 只有类型);【保守白名单】—— 只列无争议公开字段,
+ *     PII(收货地址/recipient_code)与身份/内部字段明确【排除】,全记录走 party-gated /api/orders/:id。
+ *     白名单是读边界 + 元规则#3 的安全决策,宁缺勿滥。
+ *   coverage/lock 由 tests/test-order-lifecycle-contract.ts 守(每状态有含义 + 每转移序列化 + 无 PII 泄漏)。
+ */
+import { orderLifecycleContract } from '../layer0-foundation/L0-2-state-machine/transitions.js';
+import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
+// order 实体【保守公开字段】+ 含义。刻意不含 PII / 身份 / 内部结算字段(见 pii_excluded)。
+const ORDER_PUBLIC_FIELDS = [
+    { field: 'id', type: 'string', meaning: '订单 ID / order id' },
+    { field: 'product_id', type: 'string', meaning: '商品/二手物品 ID / product (or secondhand item) id' },
+    { field: 'status', type: 'enum', meaning: '当前状态(见 lifecycle.states)/ current lifecycle state' },
+    { field: 'source', type: 'enum', meaning: "'shop' | 'secondhand' —— 渠道 / order channel" },
+    { field: 'quantity', type: 'integer', meaning: '数量 / quantity' },
+    { field: 'unit_price', type: 'number', meaning: '单价(下单快照)/ unit price (order-time snapshot)' },
+    { field: 'total_amount', type: 'number', meaning: '买家支付总额 / total paid by buyer' },
+    { field: 'fulfillment_mode', type: 'enum', meaning: "'shipping' | 'in_person' —— 履约方式 / fulfilment mode" },
+    { field: 'created_at', type: 'datetime', meaning: '下单时间 / created' },
+    { field: 'updated_at', type: 'datetime', meaning: '最后更新 / last updated' },
+    { field: 'accept_deadline', type: 'datetime', meaning: '卖家接单截止(超时→fault_seller)/ seller-accept deadline' },
+    { field: 'ship_deadline', type: 'datetime', meaning: '发货截止 / ship deadline' },
+    { field: 'delivery_deadline', type: 'datetime', meaning: '投递截止 / delivery deadline' },
+    { field: 'confirm_deadline', type: 'datetime', meaning: '买家确认截止(超时→自动确认)/ buyer-confirm deadline' },
+    { field: 'stake_backing', type: 'number', meaning: 'RFC-008 该单赔付背书额(0=起步免赔付)/ per-order stake backing (0 = bootstrap no-payout)' },
+    { field: 'decline_reason_code', type: 'enum', meaning: 'RFC-007 卖家拒单原因码 / seller decline reason code' },
+    { field: 'declined_at', type: 'datetime', meaning: 'RFC-007 拒单时间 / decline timestamp' },
+];
+// 明确【不公开】—— 安全/隐私边界声明(让集成方知道这些存在但只对当事人,经 party-gated 端点)
+const ORDER_PII_OR_PRIVATE = [
+    'shipping_address (PII — 元规则#3)', 'recipient_code (PII)', 'buyer_id / seller_id / logistics_id (party identities — 经 /api/orders/:id 对当事方可见)',
+    'escrow_amount / settled_* / commission internals (内部结算)',
+];
+// product 实体【保守公开字段】—— 买家/agent 选购 + 验证所需,排除内部审核/排序内参。
+const PRODUCT_PUBLIC_FIELDS = [
+    { field: 'id', type: 'string', meaning: '商品 ID (prd_xxx) / product id' },
+    { field: 'seller_id', type: 'string', meaning: '卖家 ID(公开,店铺主体)/ seller id (public — the shop)' },
+    { field: 'title', type: 'string', meaning: '标题(按 buyer 语言回落)/ title (localized w/ fallback)' },
+    { field: 'description', type: 'string', meaning: '描述 / description' },
+    { field: 'price', type: 'number', meaning: '价格(以 protocol-status 报价币种计)/ price' },
+    { field: 'currency', type: 'string', meaning: '币种 / currency' },
+    { field: 'stock', type: 'integer', meaning: '库存(下单 expected_price/stock 守卫见 ②)/ stock' },
+    { field: 'category', type: 'string', meaning: '类目 / category' },
+    { field: 'images', type: 'json', meaning: '图片路径数组 / image paths (JSON array)' },
+    { field: 'specs', type: 'json', meaning: '规格键值 / spec key-values' },
+    { field: 'estimated_days', type: 'json', meaning: '预计时效 / estimated fulfilment days' },
+    { field: 'commission_rate', type: 'number', meaning: '分享佣金率(推广方可得)/ promoter commission rate' },
+    { field: 'stake_amount', type: 'number', meaning: 'RFC-008 卖家为该品质押额(买家保护信号)/ seller stake on this product' },
+    { field: 'completion_count', type: 'integer', meaning: '累计成交数(社会证明)/ completed sales' },
+    { field: 'total_likes', type: 'integer', meaning: '点赞数 / likes' },
+    { field: 'content_hash', type: 'string', meaning: '商品详情 canonical JSON 的 sha256(可验,见 ⑤)/ sha256 of canonical detail (verifiable)' },
+    { field: 'content_signature', type: 'string', meaning: '卖家对 content_hash 的签名(P2P 模式自证)/ seller signature over content_hash' },
+    { field: 'status', type: 'enum', meaning: "'active' | 'warehouse' | 'deleted' —— 上架状态 / listing status" },
+    { field: 'created_at', type: 'datetime', meaning: '创建 / created' },
+    { field: 'updated_at', type: 'datetime', meaning: '更新 / updated' },
+];
+const PRODUCT_PRIVATE_OR_INTERNAL = [
+    'claim_loss_count (内部审核:声明不实累计,≥3 自动下架)',
+    'internal ranking inputs (last_sold_at / unique_sharer_count 等用于排序,非契约字段)',
+    'cost / margin (协议不存卖家成本)',
+];
+// dispute 实体 = 【裁决后公开脱敏版 dispute_cases】(非私域 disputes)。amount 分桶、argument 脱敏、buyer 身份不外露。
+const DISPUTE_PUBLIC_FIELDS = [
+    { field: 'id', type: 'string', meaning: '公开判例 ID (dcase_xxx) / public case id' },
+    { field: 'order_id', type: 'string', meaning: '关联订单 / order id' },
+    { field: 'product_id', type: 'string', meaning: '关联商品(按品查判例)/ product id' },
+    { field: 'seller_id', type: 'string', meaning: '卖家 ID(公开,信誉相关)/ seller id (public)' },
+    { field: 'category_tag', type: 'enum', meaning: '物流/质量/描述不符/售后/拒收/其他 / dispute category' },
+    { field: 'winner', type: 'enum', meaning: "'buyer' | 'seller' | 'split' | 'dismissed' —— 裁决结果 / outcome" },
+    { field: 'resolution', type: 'string', meaning: '简短人读判决(如"全额退款")/ short human-readable resolution' },
+    { field: 'amount_bucket', type: 'enum', meaning: "'0-100' | '100-500' | '500-2000' | '2000+' —— 金额【分桶】非精确(隐私)/ bucketed amount, not exact" },
+    { field: 'buyer_argument', type: 'string', meaning: '买家陈述(脱敏)/ buyer statement (redacted)' },
+    { field: 'seller_argument', type: 'string', meaning: '卖家陈述(脱敏)/ seller statement (redacted)' },
+    { field: 'ruling_text', type: 'string', meaning: '仲裁员判决书(脱敏)/ arbitrator ruling (redacted)' },
+    { field: 'fairness_yes', type: 'integer', meaning: '社区"公正"投票数 / community fairness up-votes' },
+    { field: 'fairness_no', type: 'integer', meaning: '社区"不公"投票数 / fairness down-votes' },
+    { field: 'published_at', type: 'datetime', meaning: '公开发布时间 / published' },
+];
+const DISPUTE_PRIVATE_OR_INTERNAL = [
+    'buyer_id (注释明示"仅内部使用,不外露")',
+    'dispute_id (原始 disputes.id,内部追溯)',
+    'live case 全文(证据/PII/未脱敏陈述)走 party + arbitrator-gated GET /api/disputes/:id —— dispute_cases 是【裁决后】脱敏快照',
+];
+export function buildEntityDictionary() {
+    return {
+        contract_version: CONTRACT_VERSION,
+        software_version: SOFTWARE_VERSION,
+        note: 'RFC-011 §① machine-readable entity dictionary (order / product / dispute). Order lifecycle is generated from the protocol state machine (doc=code). Field lists are a conservative PUBLIC subset — PII/identity/internal fields are excluded and only reachable by parties via party-gated endpoints. The public "dispute" entity is the redacted post-ruling dispute_cases; the live case is party+arbitrator-gated. Full read access follows the capability matrix (§② /.well-known/webaz-capabilities.json). Intent→action routing: goal index (§① /.well-known/webaz-goals.json).',
+        entities: {
+            order: {
+                kind: 'trade',
+                public_fields: ORDER_PUBLIC_FIELDS,
+                pii_excluded: ORDER_PII_OR_PRIVATE,
+                full_record: 'GET /api/orders/:id (party-gated)',
+                lifecycle: orderLifecycleContract(),
+                verifiable: {
+                    state_changes: 'observable via GET /api/agent/events (§⑥), integrity-verifiable via GET /api/orders/:id/chain (§⑤)',
+                },
+            },
+            product: {
+                kind: 'listing',
+                public_fields: PRODUCT_PUBLIC_FIELDS,
+                pii_excluded: PRODUCT_PRIVATE_OR_INTERNAL,
+                full_record: 'GET /api/products/:id (public for active listings)',
+                list: 'GET /api/search (strict match — see goal index / §② read scope "search")',
+                verifiable: {
+                    detail: 'content_hash = sha256(canonical detail); content_signature = seller signature (P2P self-attestation). See verifiability index (§⑤) external_anchor for real-world ownership/authenticity anchoring.',
+                },
+            },
+            dispute: {
+                kind: 'judicial',
+                note: 'PUBLIC entity = dispute_cases — the post-ruling, redacted snapshot. The live case (disputes) with full evidence/PII is party + arbitrator-gated.',
+                public_fields: DISPUTE_PUBLIC_FIELDS,
+                pii_excluded: DISPUTE_PRIVATE_OR_INTERNAL,
+                full_record: 'GET /api/disputes/cases/:case_id (public, redacted)',
+                list: 'GET /api/disputes/cases · GET /api/disputes/cases/by-product/:product_id',
+                live_case: 'GET /api/disputes/:id (party + arbitrator-gated; full evidence, not redacted)',
+                lifecycle: 'dispute transitions are part of the order lifecycle (see entities.order.lifecycle: disputed / fault_* / resolved_* / refunded_* states)',
+            },
+        },
+        goal_index: 'GET /.well-known/webaz-goals.json — intent → capability action (§②) + endpoint + MCP tool + PWA page (self-routing).',
+    };
+}

package/dist/pwa/goal-index.js

@@ -0,0 +1,60 @@
+/**
+ * RFC-011 §① 目标索引 —— intent → 怎么做:能力 action(②)+ REST endpoint + MCP 工具 + PWA 页。
+ *
+ * 泛化自 MCP `webaz_info.search_routing`(#1072,zh/搜索/MCP-only)→ 协议级、非 MCP 集成方也能自路由。
+ *
+ * doc=code 防漂移锁(关键):每条目标的 `action` 要么是 `open`(开放读),要么必须是
+ * capability matrix(②)里真实存在的 token —— write_action 或 read_scope。
+ * `assertGoalActionsValid()` + tests/test-goal-index.ts 守门:引用不存在的能力 = 测试红。
+ * 这样 goal-index 永远和 enforced 边界一致,不会指向幽灵能力。
+ */
+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: "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: '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.' },
+    // ── 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: '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: '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)' },
+];
+/** doc=code 锁:返回非法引用(action 既非 'open' 也不在 ② capability matrix token 集)的目标,空数组=自洽。 */
+export function invalidGoalActions() {
+    const m = capabilityMatrix();
+    const valid = new Set(['open']);
+    for (const w of m.write_actions)
+        valid.add(w.action);
+    for (const r of m.read_scopes)
+        valid.add(r.scope);
+    return GOALS.filter(g => !valid.has(g.action)).map(g => ({ goal: g.goal, action: g.action }));
+}
+export function buildGoalIndex() {
+    return {
+        contract_version: CONTRACT_VERSION,
+        software_version: SOFTWARE_VERSION,
+        note: 'RFC-011 §① goal index — maps an integrator agent\'s INTENT to the capability action (§②), the REST endpoint, the MCP tool, and the PWA page, so a (non-MCP) agent can self-route from goal to action. Each goal.action is "open" (public read) or a real token from the capability matrix (§② /.well-known/webaz-capabilities.json) — validated by tests/test-goal-index.ts (doc=code, no phantom capabilities). To exercise a write action, declare its scope per docs/INTEGRATOR.md (§③).',
+        capability_matrix: 'https://webaz.xyz/.well-known/webaz-capabilities.json',
+        goals: GOALS,
+    };
+}