@seasonkoh/webaz 0.1.15 → 0.1.17

package/LICENSE

@@ -16,7 +16,7 @@ Business Source License 1.1
   Change License:        MIT
   
   For information about alternative licensing arrangements for the
-  Licensed Work, please contact seasons.agents@gmail.com.
+  Licensed Work, please contact licensing@webaz.xyz.
 License text copyright © 2024 MariaDB plc, All Rights Reserved. “Business Source License” is a trademark of MariaDB plc.
 
 Terms

package/NOTICE

@@ -0,0 +1,58 @@
+WebAZ — Licensing Notice
+=========================
+
+Copyright (c) 2026 seasonsagents-art and WebAZ contributors
+
+
+Current License (since 2026-05-18)
+----------------------------------
+
+Business Source License 1.1 (BUSL-1.1).
+See LICENSE for full terms.
+
+  Licensor:              seasonsagents-art
+  Licensed Work:         WebAZ — Agent-native decentralized commerce protocol
+  Additional Use Grant:  You may make production use of the Licensed Work,
+                         provided that your use does not include offering the
+                         Licensed Work to third parties as a hosted or managed
+                         service that is substantially similar to, or competes
+                         with, the WebAZ commerce protocol service operated by
+                         the Licensor.
+  Change Date:           2030-05-18
+  Change License:        MIT
+
+On the Change Date the Licensed Work automatically converts to the
+Change License (MIT) for all purposes.
+
+
+Historical Licensing
+--------------------
+
+All versions and git commits published BEFORE 2026-05-18 were released under
+the MIT License. That grant is irrevocable. Copies, forks, and derivatives
+made from those earlier versions remain MIT-licensed in perpetuity.
+
+The license change applies only to commits and releases dated on or after
+2026-05-18.
+
+
+Third-Party Components
+----------------------
+
+This software incorporates third-party open-source libraries listed in
+package.json. Each is governed by its own license; see the respective
+package's LICENSE file for terms.
+
+
+Trademarks
+----------
+
+"WebAZ" and the WebAZ logo are trademarks of seasonsagents-art. The license
+does not grant any trademark rights.
+
+
+Questions
+---------
+
+For licensing questions, including commercial license inquiries that fall
+outside the Additional Use Grant above, contact: licensing@webaz.xyz

package/README.md

@@ -6,7 +6,12 @@
 
 [![npm](https://img.shields.io/npm/v/@seasonkoh/webaz.svg)](https://www.npmjs.com/package/@seasonkoh/webaz)
 [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-active-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=webaz)
-[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-orange.svg)](LICENSE) [![Change Date: 2030-05-18](https://img.shields.io/badge/Change%20Date-2030--05--18-blue.svg)](NOTICE)
+[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-orange.svg)](LICENSE) [![Change Date: 2030-05-18](https://img.shields.io/badge/Change%20Date-2030--05--18-blue.svg)](NOTICE) ![Status: Pre-launch](https://img.shields.io/badge/Status-Pre--launch-yellow.svg)
+
+> 🚧 **Pre-launch · 预发布阶段** — v1.0 公示中（起算 2026-05-31）· 0 真用户 · verifier + arbitrator 全为 fixture · 经济模型未结算 · 不建议生产使用。
+> 🚧 **Pre-launch stage** — v1.0 public-notice period (started 2026-05-31) · 0 real users · verifier + arbitrator are fixtures · economic model un-settled · **not for production use**.
+>
+> 详见 / Details: [`docs/CHARTER.md`](docs/CHARTER.md) · [`docs/META-RULES-FULL.md`](docs/META-RULES-FULL.md) · [`docs/ECONOMIC-MODEL.md`](docs/ECONOMIC-MODEL.md) · [`/api/protocol-status`](https://webaz.xyz/api/protocol-status)
 
 让 AI Agent 成为去中心化商业协议的原生参与者。卖家零额外工作量接入新渠道，买家通过 Agent 自动购物，人类与 AI 在同一协议上平等参与。
 
@@ -83,7 +88,16 @@
 
 ### 方式一：Claude MCP 接入（Agent 原生体验）
 
-**1. 添加到 Claude Desktop 配置**
+MCP server 有两种模式 / The MCP runs in one of two modes：
+
+| 模式 / Mode | 数据源 | 用途 | 如何触发 |
+|---|---|---|---|
+| 🟢 **NETWORK** | `webaz.xyz` 共享生产网络（带你的 `api_key`） | 真实加入网络、和别人交易 | 配了 `WEBAZ_API_KEY` |
+| 🟡 **SANDBOX** | 本机本地 SQLite（`~/.webaz/webaz.db`） | 离线试玩 / 开发，**与全网隔离** | 未配 `WEBAZ_API_KEY`（默认） |
+
+> 🟢 NETWORK = your agent acts on the live shared network. 🟡 SANDBOX = local-only, private to your machine, **not** the live network. Every tool result is stamped with `_mode` so you always know which one you're in.
+
+**A. 先离线试玩（SANDBOX，零配置）**
 
 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
 
@@ -98,15 +112,35 @@
 }
 ```
 
-重启 Claude Desktop。无需手动安装，`npx` 会自动下载运行。
+重启 Claude Desktop。`npx` 自动下载运行。此时所有数据都在本机沙盒，可放心试 `webaz_register` / `webaz_search` / 下单全流程。
+
+**B. 真正加入网络（NETWORK）**
+
+1. 在 [webaz.xyz](https://webaz.xyz) 注册账号（需邀请码；注册时绑定 Passkey 成为可问责真人）
+2. 「我的 / 设置」→ 复制 `api_key`
+3. 配置里加上 `WEBAZ_API_KEY` 环境变量：
+
+```json
+{
+  "mcpServers": {
+    "webaz": {
+      "command": "npx",
+      "args": ["-y", "@seasonkoh/webaz"],
+      "env": { "WEBAZ_API_KEY": "你的_api_key" }
+    }
+  }
+}
+```
+
+> NETWORK 模式下 `webaz_register` **不自助建号**（账号必须由真人在 webaz.xyz 创建 + 绑 Passkey，这是协议的可问责性要求）。注册以外的交易工具——搜索 / 锁价 / 下单 / 上架 / 履约 / 查单——都直接在共享网络上跑。
 
-**3. 开始使用**
+**C. 开始使用**
 
 在 Claude 对话里说：
 
-> "帮我在 WebAZ 注册一个买家账号，然后搜索一下有什么商品"
+> "帮我在 WebAZ 搜索一下有什么商品，挑性价比高的下单"
 
-Claude 会自动调用 `webaz_register` 和 `webaz_search` 完成操作。
+Claude 会自动调用 `webaz_search` → `webaz_verify_price` → `webaz_place_order` → `webaz_get_status` 完成发现→下单→追踪全流程。
 
 ---
 
@@ -234,6 +268,32 @@ npm run test-manifest# 测试协议 Manifest
 
 ---
 
+## 架构总览 / Architecture map
+
+> 给 AI agent / 新贡献者:不用扫全仓,从下表对应层入手。改代码的 agent 请先读 [`AGENTS.md`](AGENTS.md)。
+> For AI agents / new contributors: don't scan the whole repo — start from the layer your change belongs to. Agents modifying code: read [`AGENTS.md`](AGENTS.md) first.
+
+一套代码两个运行时:**MCP server**(`src/mcp.ts`,给 AI agent)+ **PWA**(`src/pwa/`,给人类)—— 同后端、同规则。
+One codebase, two runtimes: the **MCP server** (for AI agents) and the **PWA** (for humans) share the same backend and rules.
+
+代码分 8 层(`src/layerN-*/`,由底向上依赖)/ Code is layered (`src/layerN-*/`, bottom-up):
+
+| Layer | 它是什么 / What |
+|---|---|
+| `layer0-foundation` | DB schema · 订单**状态机** state-machine · manifest |
+| `layer1-agent` | **MCP server**(`L1-1-mcp-server/server.ts`，最常改)· 身份 / 外部锚点 identity / anchor |
+| `layer2-business` · `layer2-commerce` | 通知 / SNF / anchor registry 等业务 business logic |
+| `layer3-trust` | 争议引擎 dispute engine |
+| `layer4-economics` | 声誉 reputation · 技能市场 skill-market |
+| `layer5-decentralized` · `layer6-scale` | 治理 / 扩展(部分后续阶段)governance / scale (some reserved) |
+
+关键入口 / Key entry files:
+- `src/mcp.ts` → tools 实现在 `src/layer1-agent/L1-1-mcp-server/server.ts`
+- `src/pwa/server.ts` + `src/pwa/routes/` → PWA + HTTP API(人 / agent 共用生产端点)
+- `src/cron-enforcement.ts` → 协议自动判责执行(超时→处置)auto state-machine enforcement
+
+---
+
 ## 当前阶段
 
 **Phase 0 · 概念验证** ✅
@@ -315,3 +375,21 @@ npm run test-manifest# 测试协议 Manifest
 - [ ] 评价系统（结构化 1-5 星，反哺声誉）
 - [ ] 证据上传通道（争议附图）
 - [ ] 治理 DAO
+
+---
+
+## 联系 / Contact
+
+| 用途 / Purpose | Email | 详情 / Details |
+|---|---|---|
+| 通用咨询 / General inquiries | `contact@webaz.xyz` | — |
+| 安全漏洞 / Security vulnerabilities | `security@webaz.xyz` | [SECURITY.md](SECURITY.md) — 强烈优先用 [GitHub Security Advisory](https://github.com/seasonsagents-art/webaz/security/advisories) / Strongly prefer Advisory |
+| 行为准则举报 / Code of Conduct reports | `conduct@webaz.xyz` | [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) §7 |
+| BSL 商业授权 / Commercial licensing | `licensing@webaz.xyz` | [LICENSE](LICENSE) / [NOTICE](NOTICE) |
+
+> 📬 上述均为 Cloudflare Email Routing forwarding alias;phase A solo 阶段统一转发到创始人个人邮箱,响应水平为**个人级**(非企业 SLA);phase B+ 形成 maintainer 群后会切到团队 triage(无需改文档)。
+> 📬 All addresses are Cloudflare Email Routing forwarding aliases; in phase A solo, they route to the founder's personal inbox with **personal-level response** (not enterprise SLA); phase B+ will switch to maintainer team triage (no doc change needed).
+
+**Bug 报告 / 功能想法 / RFC**:走 [GitHub Issues](https://github.com/seasonsagents-art/webaz/issues) 或 [Discussions](https://github.com/seasonsagents-art/webaz/discussions);PR 流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+**Bug reports / feature ideas / RFCs**: please use [GitHub Issues](https://github.com/seasonsagents-art/webaz/issues) or [Discussions](https://github.com/seasonsagents-art/webaz/discussions); PR workflow per [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/layer0-foundation/L0-2-state-machine/engine.js

@@ -5,6 +5,9 @@
  * 1. transition()     — 执行状态转移（验证权限 + 记录历史）
  * 2. checkTimeouts()  — 扫描超时订单，自动判责
  * 3. getStatus()      — 查询订单当前状态和责任方
+ *
+ * 关联 / Related: AGENTS.md · 元规则 #1 当一切可见 / #2 代码即规则(状态机=规则的代码化,改这里=改协议行为) ·
+ *   合法转移表见 transitions.ts · 协议级改动审批见 CHARTER §3.2
  */
 import { generateId } from '../L0-1-database/schema.js';
 import { appendOrderEvent } from './order-chain.js';