# Wasmeld 组件包

**状态：** Implemented

**格式版本：** 1

`.wasmpkg` 是平台内部发布 WebAssembly Component 的单文件制品。文件使用 ZIP
容器，扩展名固定为 `.wasmpkg`，并且只能包含两个根目录条目：

```text
echo-0.1.0.wasmpkg
├── package.toml
└── component.wasm
```

`package.toml` 示例：

```toml
schema_version = 1
id = "echo"
revision = "0.1.0"
world = "component:echo/echo-component@0.1.0"
component = "component.wasm"
sha256 = "..."
```

包中不包含内存、Fuel、超时或 mailbox 等部署策略。这些限制由
`wasmeld-console` 的 `registration_limits` 注入，组件发布者不能通过上传制品扩大
Sandbox 权限。

## 组件配置

组件必须是 `cdylib`，并在 `Cargo.toml` 中声明平台服务 ID：

```toml
[lib]
crate-type = ["cdylib"]

[package.metadata.wasmeld]
id = "echo"
world = "component:echo/echo-component@0.1.0"
```

版本直接使用 `[package].version`。`world` 必须是组件选择的完整、带版本 WIT World；
打包工具会将它写入制品，控制台不需要手工填写。

组件的 WIT 依赖由同目录的 `wasmeld.toml` 和 `wit.lock` 管理。`pack` 会在 Cargo
编译前自动生成 `wit/deps`；CI 应传入 `--locked`，禁止依赖摘要发生漂移。

## 打包

从项目根目录运行：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  pack components/echo/Cargo.toml --locked
```

命令默认使用 Rust `1.90.0` 构建 `wasm32-wasip2` release Component，并输出：

```text
dist/echo-0.1.0.wasmpkg
```

可以覆盖输出路径，或者复用已经构建的 Component：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  pack components/echo/Cargo.toml \
  --output dist/echo.wasmpkg \
  --no-build
```

通过 `WASMELD_COMPONENT_TOOLCHAIN` 可以覆盖组件构建工具链。

## 注册

管理 API 只接收一个 multipart 字段：

```bash
curl -F package=@dist/echo-0.1.0.wasmpkg \
  http://127.0.0.1:8080/api/v1/services
```

Console 在写入制品目录前执行以下校验：

- ZIP 恰好包含 `package.toml` 和 `component.wasm`
- schema、服务 ID、版本和 WIT World 合法
- 解压后的 Component 未超过平台上限
- Component 的 SHA-256 与 manifest 一致
- Wasmtime 能编译 Component，且 imports 符合 Sandbox 白名单
- 同一服务 ID 和版本尚未注册

校验成功后，服务以 `stopped` 状态注册。启动 Actor 仍是独立的管理操作。