docs: document Wasmeld architecture and workflows

- describe resident Runtime boundaries and sandbox guarantees - specify component archive and host capability contracts - document Console ownership and persistence behavior - explain versioned WIT Registry, lock files, and path replace - provide startup, packaging, publication, and dependency commands
2026-07-27 05:03:24 +08:00
parent 8de300b634
commit ad7d8cdd72
6 changed files with 763 additions and 0 deletions
@@ -0,0 +1,145 @@
+# WIT Package 管理
+
+**状态：** Implemented
+
+**Manifest 版本：** 1
+
+**Lock 版本：** 1
+
+## 边界
+
+`wasmeld-console` 作为版本化 WIT Registry 和管理面。组件构建侧由 `wasmeld`
+解析依赖、锁定摘要并生成本地 `wit/deps`。`wit-bindgen` 始终只读取本地文件，
+Component 运行时不访问 Registry。
+
+```text
+WIT Git tag
+    |
+    v
+Wasmeld Registry
+    |
+    v
+wasmeld -> wit.lock -> wit/deps -> wit-bindgen
+```
+
+WIT 源码不按版本复制目录。每个 package 只维护当前源码，发布时用
+`service/v1.0.0`、`clock/v1.1.0` 等 Git tag 标记源码版本。Registry 保存由
+Component Model 工具链编码的标准二进制 WIT Package，并从制品本身解析包名、
+版本、直接依赖和 SHA-256。相同包名和版本不可覆盖。
+
+## 组件目录
+
+```text
+components/clock-probe/
+├── Cargo.toml
+├── wasmeld.toml
+├── wit.lock
+├── src/lib.rs
+└── wit/
+    ├── world.wit
+    └── deps/        # 自动生成，不提交
+```
+
+`wasmeld.toml` 当前只接受精确版本：
+
+```toml
+schema_version = 1
+
+[registry]
+url = "http://127.0.0.1:8080"
+
+[dependencies]
+"wasmeld:clock" = "0.1.0"
+"wasmeld:service" = "0.1.0"
+
+[replace."wasmeld:clock"]
+path = "../../wit/clock"
+
+[replace."wasmeld:service@0.1.0"]
+path = "../../wit/service"
+```
+
+精确版本 replace 的优先级高于包级 replace。只有根组件的 replace 生效；依赖包
+自身不能修改整个依赖图。替换目录声明的 WIT package 名称和版本必须与依赖完全
+相同。没有 replace 的直接依赖和传递依赖从 `[registry].url` 获取。
+
+## 锁文件
+
+`wit.lock` 必须提交：
+
+```toml
+schema_version = 1
+
+[[package]]
+name = "wasmeld:clock"
+version = "0.1.0"
+source = "registry+http://127.0.0.1:8080"
+sha256 = "..."
+replaced = false
+```
+
+Registry 依赖的摘要覆盖完整二进制包；path replace 的摘要覆盖包目录下排序后的
+顶层 `.wit` 文件名和内容。`--locked` 在安装 `wit/deps` 前比较完整传递依赖图、
+来源和摘要，不一致时构建失败。
+
+## 命令
+
+```bash
+# 将 WIT 源码编码成标准二进制 WIT Package
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit build wit/service
+
+# 构建并发布；也可用 WASMELD_REGISTRY 设置 Registry
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit publish wit/service --registry http://127.0.0.1:8080
+
+# 获取依赖并更新 wit.lock
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit fetch --manifest components/clock-probe/wasmeld.toml
+
+# 验证锁文件，不更新
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit fetch --manifest components/clock-probe/wasmeld.toml --locked
+
+# 查看实际来源
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit graph --manifest components/clock-probe/wasmeld.toml
+
+# 添加或删除本地替换
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit replace wasmeld:clock@0.1.0 \
+  --path ../../wit/clock \
+  --manifest components/clock-probe/wasmeld.toml
+
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit replace wasmeld:clock@0.1.0 \
+  --drop \
+  --manifest components/clock-probe/wasmeld.toml
+```
+
+`pack` 自动执行相同的同步步骤：
+
+```bash
+cargo run -p wasmeld-package --bin wasmeld -- \
+  pack components/clock-probe/Cargo.toml --locked
+```
+
+## Registry API
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `GET` | `/api/v1/wit/packages` | 列出全部包版本 |
+| `POST` | `/api/v1/wit/packages` | multipart 发布 `package.wasm` |
+| `GET` | `/api/v1/wit/packages/{namespace}/{name}/{version}` | 查询元数据 |
+| `GET` | `/api/v1/wit/packages/{namespace}/{name}/{version}/content` | 下载二进制包 |
+
+Console 管理面提供同一 Registry 的列表、发布和下载操作。Registry 元数据不接受
+客户端填写，服务端以二进制包解析结果为准。
+
+## 当前边界
+
+- 依赖版本必须是精确 SemVer，不解析版本范围。
+- Registry 使用本地文件系统持久化，默认目录为 `var/wasmeld/wit-packages`。
+- Registry 不保存 Git 仓库或源码；Git tag 与 commit 由源码仓库管理。
+- 本地 `replace` 只支持目录，不支持 Git replace。
+- 暂不包含认证、权限、废弃标记和垃圾回收。